Getting Started

Die vorliegende Anleitung führt durch die Installation der Entwicklungsumgebung bis zur Ausführung der automatisierten Tests der Wingolfsplattform.

Betriebsystem:

• Aufgrund ihrer aktuellen Popularität geht diese Anleitung exemplarisch von einer frischen Installation der Linux-Distribution Ubuntu aus.
• [Tipps für Gentoo](Tipps für Gentoo)
• [Tipps für Mac OS](Tipps für Mac OS)

Schritt 1: Einführende Literatur

Hier eine kurze Auswahl einführender Literatur zur Versionsverwaltungs-Software git und zum Ruby-on-Rails-Framework, die helfen soll, sich überblicksartig mit diesen Werkzeugen vertraut zu machen.

Git

• http://try.github.com/
• http://gitreal.codeschool.com/
• https://help.github.com/articles/set-up-git
• http://git-scm.com/book/ch1-3.html

Ruby on Rails

• http://railscasts.com/episodes/310-getting-started-with-rails
• http://ruby.railstutorial.org/ruby-on-rails-tutorial-book
• http://guides.rubyonrails.org/getting_started.html

Schritt 2: Versionskontrolle mit Git

git installieren

Unter Ubuntu wird git wie folgt installiert.

# bash 
sudo apt-get install git git-completion

git konfigurieren

Bevor fortgefahren wird, ist es wichtig, dass git korrekt konfiguriert wird. Insbesondere ist es wichtig, die Daten zur eigenen Identifikation anzugeben, damit andere Entwickler sehen können, wer welche Änderungen am Code vorgenommen hat.

# bash

# Identifikation:
git config --global user.name 'Your Name'
git config --global user.email '[email protected]'

# Empfohlene Befehls-Kürzel:
git config --global alias.st status
git config --global alias.ci commit
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.graph 'log --oneline --decorate --graph'
git config --global alias.last 'log -1 HEAD'

# Weitere Konfiguration:
git config --global core.editor 'emacs' # or 'vi' or 'nano' or 'gedit' or your favorite editor.
git config --global color.branch auto
git config --global color.diff auto
git config --global color.interactive auto
git config --global color.status auto

Github-Account

Zum Zugriff auf das Repository auf Github ist ein Github-Account erforderlich, der hier angelegt werden kann.

Zugriff per SSH einrichten

Der Zugriff auf die Repositories erfolgt über das SSH-Protokoll. Zum einfacheren Zugriff sollte ein SSH-Key erzeugt und bei Github hinterlegt werden:

# bash
ssh-keygen -t rsa -C "[email protected]"

Der so erzeugte Schlüssel kann mit cat .ssh/id_rsa.pub angezeigt werden. Der so angezeigte Schlüssel muss dann auf https://github.com/settings/ssh kopiert werden.

Weitere Informationen: https://help.github.com/articles/generating-ssh-keys

Projekt klonen

# bash
mkdir ~/rails
cd ~/rails
git clone [email protected]:fiedl/wingolfsplattform.git

Damit wird das Repository in das lokale Verzeichnis ~/rails/wingolfsplattform kopiert.

Schritt 3: Hilfspakete installieren

Um die Applikation lokal auszuführen, wird eine Reihe von Hilfspaketen benötigt:

libruby1.9.1 libssl-dev g++ libxml2 libxslt-dev libreadline-dev libicu-dev imagemagick libmagick-dev libmagickwand-dev pwgen sendmail mysql-server-5.5 libmysql++-dev libmysqlclient-dev

Unter Ubuntu beispielsweise können diese mit apt-get install installiert werden.

# bash
sudo apt-get install aptitude
sudo aptitude -y install libruby1.9.1 libssl-dev g++ libxml2 libxslt-dev libreadline-dev libicu-dev imagemagick libmagick-dev libmagickwand-dev pwgen sendmail
sudo aptitude remove graphicsmagick-libmagick-dev-compat
sudo aptitude install libmagickwand-dev
sudo aptitude -y install mysql-server-5.5 libmysql++-dev libmysqlclient-dev

Andere Systeme: Tipps für Gentoo

Trouble Shooting: Es muss sichergestellt werden, dass /usr/sbin/sendmail auf der Entwicklungsmaschine installiert ist. Der Mailer erzeugt keine Fehlermeldung. Wenn man aber keine E-Mails von der Entwicklungsmaschine erhält, findet sich vielleicht etwas im Log: /var/log/mail.err.

Es muss sichergestellt sein, dass in /etc/hosts die Loop-Back-Schleife richtig definiert ist, z.B.

# /etc/hosts
# ...
127.0.0.1       localhost localhost.localdomain my-dev-box
# ...

Weitere Informationen: http://serverfault.com/questions/58363/my-unqualified-host-name-foo-bar-unknown-problem

Schritt 4: Ruby mit rbenv

Wir empfehlen die Verwendung von rbenv, einer Software zur Verwaltung verschiedener Ruby-Versionen auf einer Entwicklungsmaschine. Alternativ kann stattdessen beispielsweise rvm oder die entsprechende Ruby-Version aus den Paketquellen des Systems verwendet werden.

Installation von rbenv

1. Optional: Gegebenenfalles Ruby über die systemeigene Paketverwaltung deinstallieren.
2. Optional: Gegebenenfalles rvm entfernen.
3. rbenv installieren:

# bash
git clone git://github.com/sstephenson/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc # oder .zshrc{,.local} oder ...
echo 'eval "$(rbenv init -)"' >> ~/.bashrc # oder .zshrc{,.local} oder ...
exec $SHELL -l
git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build

Weitere Informationen: https://github.com/sstephenson/rbenv/#installation

Installation einer Ruby-Version

Aktuell verwenden wir jeweils die Ruby-Version, die in der Datei .ruby-version angegeben ist.

Eine Ruby-Version lässt sich mit rbenv wie folgt installieren.

# bash
rbenv install 2.0.0-p247
rbenv rehash
exec $SHELL -l

1. Optional: Sollte man jedoch auch an anderen Ruby-Programmen arbeiten, empfiehlt sich das Setzen einer globalen Version:

# bash
rbenv global 2.0.0-p247

2. Die virtuellen Ruby-Binaries der Pfad-Variable hinzufügen:

# bash
echo 'export PATH="$HOME/.rbenv/shims:$PATH"' >> ~/.bashrc # oder .zshrc{,.local}

3. Die Shell reinitialisieren:

# bash
exec $SHELL -l

4. Überprüfen, ob alles funktioniert. Das folgende Kommando sollte die aktuelle Ruby-Version anzeigen:

# bash
ruby --version

Gem Bundler installieren

Ruby bringt eine eigene Paketverwaltung mit, mit dessen Hilfe schnell die Ruby-Pakete installiert werden können, die für ein Projekt notwendig sind. Die nötigen Pakete sind in der Datei Gemfile spezifiziert und können mit dem gem bundler installiert werden. Der Bundler muss hierzu vorher wie folgt installiert werden:

# bash
cd ~/rails/wingolfsplattform
gem install bundle
rbenv rehash

Ruby-Pakete für die Wingolfsplattform installieren

Nachdem der Bundler installiert ist, können die jeweils aktuellen Pakete für die Wingolfsplattform wie folgt installiert werden:

# bash
cd ~/rails/wingolfsplattform
bundle install

Schritt 5: Datenbank und Konfiguration

Um die Applikation nur kurz lokal auszurpobieren, genügt eine sqlite-Datenbank. Für ausgiebigere Tests und Weiterentwicklung wird die Verwendung einer MySQL-Datenbank empfohlen.

Installation von MySQL

# bash
sudo aptitude -y install mysql-server-5.5 libmysql++-dev libmysqlclient-dev

Konfiguration von MySQL

# bash
mysql_secure_installation

Hierbei sollte ein Passwort für den Datenbank-Root-Benutzer generiert werden (standardmäßig leer). Ein neues Passwort kann hierbei beispielsweise mit pwgen 20 generiert werden. (Sonderzeichen bereiten unter Umständen Probleme. Daher nicht die pwgen-Option -y verwenden.) Für die restlichen Einstellungen kann jeweils der Standard-Option gefolgt werden.

Als Vorlage für die Datenbank-Konfiguration liegt dem Repository eine Beispiel-Datei bei:

# bash
cp config/database.yml.example config/database.yml

Die in der MySQL-Konfiguration angegebenen Benutzerdaten für den root-Datenbankbenutzer können nun direkt in der Datenbank-Konfiguration der Applikation angegeben werden.

# config/database.yml
# ...
development:
  adapter: mysql2
  encoding: utf8
  reconnect: false
  database: wingolfsplattform_development
  pool: 5
  username: root
  password: YOUR PASSWORD HERE
  host: localhost

test:
  adapter: mysql2
  encoding: utf8
  reconnect: false
  database: wingolfsplattform_test
  pool: 5
  username: root
  password: YOUR PASSWORD HERE
  host: localhost

Weitere Schritte:

• Wenn lokal auch andere Anwendungen MySQL verwenden, sollte ein eigener Datenbank-Benutzer für die Wingolfsplattform erstellt werden.
• Falls das Root-Passwort zurückgesetzt werden muss, findet sich hier eine Anleitung.

Entwicklungs-Datenbank erstellen

Zum lokalen Betrieb der Anwendung im Entwicklungs-Modus ("development environment") muss eine entsprechende Datenbank erstellt und mit initialen Daten gespeist werden.

# bash
cd ~/rails/wingolfsplattform

# create database
bundle exec rake db:create db:migrate

# fill in initial data
bundle exec rake bootstrap:all
bundle exec rake import:corporations import:standard_workflows  # this may take some time

Redis-Datenbank

Um metrische Daten zu sammeln, z.B. CPU-Last, Anzahl der Requests, etc., verwenden wir fnordmetric. Als Datenspeicher wird eine redis-Datenbank verwendet.

Es muss also zunächst redis installiert werden:

# bash
sudo apt-get install redis-server

Dienst starten: Um die metrischen Daten aufzubereiten und eine GUI zur Darstellung zur Verfügung zu stellen, muss ein Hintergrund-Dienst gestartet werden. Dies geschieht in Schritt 8 automatisch mit. Manuell kann der Dienst jedoch wie folgt gestartet werden (Abbruch mit Ctrl-C):

# bash
cd ~/rails/wingolfsplattform
bundle exec foreman start fnordmetric

Web-Interface-GUI: http://localhost:4242

Daten zurücksetzen: Sollten die metrischen Daten zurückgesetzt werden müssen, ist dies in der Rails-Konsole mit folgendem Kommando zu erreichen. Vorsicht! Das löscht die gesamte Redis-Datenbank. Das ist nur bedenklich, falls die Redis-Datenbank auf dem Entwicklungsrechner noch für andere Zwecke verwendet wird.

# rails console   (bundle exec rails console)
Redis.new(port: 6379).flushall

Schritt 6: Automatisierte Tests

PhantomJS installieren

Als Simulator für eine JavaScript-Umgebung wird PhantomJS verwendet. PhantomJS muss separat installiert werden, da eine aktuellere Version benötigt wird als in den meisten Paketquellen vorhanden.

64bit

# bash
mkdir /tmp/phantomjs && cd /tmp/phantomjs
wget http://phantomjs.googlecode.com/files/phantomjs-1.8.1-linux-x86_64.tar.bz2
tar xf phantomjs-1.8.1-linux-x86_64.tar.bz2
sudo cp ./phantomjs-*/bin/phantomjs /usr/bin/phantomjs
rm -r /tmp/phantomjs

32bit

# bash
mkdir /tmp/phantomjs && cd /tmp/phantomjs
wget http://phantomjs.googlecode.com/files/phantomjs-1.9.0-linux-i686.tar.bz2
tar xf phantomjs-1.9.0-linux-i686.tar.bz2
sudo cp ./phantomjs-*/bin/phantomjs /usr/bin/phantomjs
rm -r /tmp/phantomjs

Weitere Informationen: http://phantomjs.org/download.html

Tests laufen lassen

# bash
cd ~/rails/wingolfsplattform
bundle exec rake db:test:prepare
bundle exec rake

Wenn alles gut geht, sollten die Tests nach einigen Minuten mit 0 failures abschließen.

Schritt 7: Anwendung im Browser öffnen

Server starten

# bash
cd ~/rails/wingolfsplattform
bundle exec rails server

Dieser Server-Prozess muss im Hintergrund weiter laufen. Es bietet sich an, ihn in einem eigenen Terminal-Tab zu starten, um die Debug-Meldungen dort lesen zu können.

Im Browser öffnen

Nach Start des Servers ist die lokale Anwendung im Browser unter der Url http://localhost:3000 erreichbar.

Benutzer erstellen

Um sich im Browser am System anzumelden, muss zunächst ein Benutzer erstellt werden:

# bash
cd ~/rails/wingolfsplattform
bundle exec rails console

# rails console
user = User.create( first_name: "Your First Name", last_name: "Your Last Name", email: "[email protected]", alias: "your.username" )
user.activate_account
Group.everyone.admins << user

Ein Passwort wird an die angegebene Adresse per E-Mail übermittelt.

Trouble Shooting

• Sollte beim Öffnen der Rails-Console ein Fehler bezüglich Readline angezeigt werden ("uninitialized constant IRB::ReadlineInputMethod::Readline (NameError)"), muss die Ruby-Version erneut installiert werden (oben wurde rb-readline via bundler installiert, da dieses Ruby-Paket im Gemfile vorkommt.): rbenv install 2.0.0-p247 CONFIGURE_OPTS="--with-readline-dir=/usr/include/readline".

• Manuelles Setzen des Passwortes: Es ist ein Passwort mit mindestens 8 Zeichen erforderlich.

# rails console
user = User.first
account = user.account
account.password = "my_secret!password"
account.save

• E-Mail kommt nicht an: Überprüfen, ob in /var/log/mail.err der Fehler My unqualified host name unknown gemeldet wird, lässt sich das Problem beheben, indem die /etc/hosts korrigiert wird: Es darf nur eine Zeile mit 127.0.0.1 beginnen. Siehe auch: http://serverfault.com/questions/58363

Schritt 8: Worker-Prozesse

Die Anwendung verwendet Worker-Prozesse, die im Hintergrund Aufgaben ausführen, etwa E-Mails bearbeiten.

Die Liste der Hintergrund-Worker-Prozesse befindet sich in der Datei Procfile im Repository. Zur Verwaltung der Worker wird foreman verwendet.

Um die Worker auf der lokalen Entwicklungsmaschine zu starten bzw. zu stoppen, sind folgende Kommandos möglich:

# bash (auf der Entwicklungsmaschine)
cd ~/rails/wingolfsplattform
foreman start  # Worker starten
foreman stop   # Worker ausschalten

Auf dem Produktiv-Server erzeugt das Deployment-Skript einen Service wingolfsplattform-workers, der die Foreman-Worker in Procfile startet. Dieser Service wird seinerseits von monit verwaltet.

Schritt 9: Kleine Helferlein

git-Branch in Shell

Bei der Arbeit in der Shell ist es hilfreich, den aktuellen Git-Branch anzeigen zu lassen. Beispielsweise:

# ~/.bashrc
# ...
PS1='\n\u@\h:\w$(__git_ps1 " (%s)")\$ '

Abkürzung für bundle exec

Um stets sicherzustellen, dass die gems in der für das Projekt richtigen Version verwendet werden, wird jeder Aufruf von Ruby-Skripten mit bundle exec gepräfixt, z.B. bundle exec rails server, bundle exec rails console oder bundle exec guard. Um Schreibaufwand zu sparen, ohne aber Bin-Stubs installieren zu müssen, empfiehlt sich ein entsprechender Kurzbefehl-Alias:

# ~/.bashrc
# ...
alias be='bundle exec'
alias bi='bundle install'
alias bu='bundle update'

Pfad-Kürzel

Es empfiehlt sich Kurzbefehle für häufig verwendete Pfade anzulegen, um beispielsweise mit dem Kurzbefehl cdw ins Verzeichnis ~/rails/wingolfsplattform zu wechseln.

# ~/.bashrc
# ...
alias cdw='cd ~/rails/wingolfsplattform'
alias cdy='cd ~/rails/wingolfsplattform/vendor/engines/your_platform'
alias cda='cd ~/rails/wingolfsplattform/vendor/engines/your_platform/app/assets/javascripts/'

Editor-Einstellungen

• Editor-Einstellungen für vim
• Mac OS: Am Besten Textmate verwenden!