Skip to content

Getting Started

Jump to bottom Edit New page
Sebastian Fiedlschuster edited this page Feb 27, 2018 · 68 revisions

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

Betriebsystem:

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

Ruby

Ruby on Rails

Schritt 2: Versionskontrolle mit Git

git installieren

Unter Ubuntu wird git wie folgt installiert.

# bash
sudo apt install git

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 forken und klonen

Der Quellcode der Wingolfsplattform ist in zwei Teile aufgeteilt. In "YourPlatform", dem größeren Teil, befindet sich die Plattform so weit, wie sie auch von anderen Organisationen genutzt werden kann. In "Wingolfsplattform" befinden sich lediglich die Wingolfs-Spezifika, z.B. die Definition von Aktivitätszahlen oder Bezirksverbänden.

Um an der Plattform mitzuentwickeln, erstellt man zunächst jeweils einen Github-Fork der beiden Projekte:

Danach wird das Projekt auf die lokale Entwicklungsmaschine geklont:

# bash
mkdir ~/rails
cd ~/rails
git clone [email protected]:your-username/wingolfsplattform.git
git clone [email protected]:your-username/your_platform.git

Damit wird das Code-Repository der Wingolfsplattform in das lokale Verzeichnis ~/rails/wingolfsplattform kopiert. Die YourPlatform-Engine, die den Großteil des Codes enthält, wird nach ~/rails/your_platform geklont.

Schritt 3: Hilfspakete installieren

Um die Applikation lokal auszuführen, wird eine Reihe von Hilfspaketen benötigt. Unter Ubuntu beispielsweise können diese mit apt-get install installiert werden.

# bash
sudo apt install libssl-dev g++ libxml2 libxslt-dev libreadline-dev libicu-dev imagemagick libmagick-dev pwgen

Andere Systeme:

Schritt 4: Ruby mit rbenv

Wir empfehlen die Verwendung von rbenv, einer Software zur Verwaltung verschiedener Ruby-Versionen auf einer Entwicklungsmaschine.

Installation von rbenv

# bash
sudo apt install rbenv ruby-build ruby-dev
rbenv init

echo 'eval "$(rbenv init -)"' >> ~/.bashrc
bash

Installation einer Ruby-Version

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

# bash
rbenv install 2.3.3
rbenv global 2.3.3
ruby --version

Schritt 5: Docker

Docker installieren:

# bash
sudo snap install docker

Den Benutzer in die Docker-Gruppe eintragen, damit man Docker steuern kann:

# bash
sudo addgroup --system docker
sudo adduser $USER docker
newgrp docker
sudo snap disable docker
sudo snap enable docker

Danach neu einloggen, damit man Mitglied der Gruppe wird.

Schritt 6: Datenbanken

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:

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

Redis-Datenbank

Zum Caching und für Worker-Abläufe verwenden wir eine Redis-Datenbank. Es muss also zunächst redis installiert werden:

# bash
sudo apt-get install redis-server

Dienst starten: Die Hintergrund-Dienste werden in der Entwicklungsumgebung mit Foreman gestartet. Weitere Informationen im Schritt 8.

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

Daten zurücksetzen: Sollten die Redis-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 7: Neo4j

Schritt X: Ruby-Pakete installieren

Bundler installieren

Ruby bringt eine eigene Paketverwaltung mit, mit deren 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 Bundler installiert werden. Der Bundler muss hierzu vorher wie folgt installiert werden:

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

Projekte lokal verbinden

Damit die lokale Entwicklungsversion der Wingolfsplattform weiß, dass sie auch den lokalen Quellcode von YourPlatform verwenden soll:

# bash
cd ~/rails/wingolfsplattform
bundle config local.your_platform ~/rails/your_platform

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 X: JavaScript

# Install nodejs.
aptitude install build-essential libssl-dev
curl -sL https://deb.nodesource.com/setup_7.x | bash
aptitude install -y nodejs
node --version
npm i -g yarn

Schritt 8: 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.

# bash
mkdir /tmp/phantomjs && cd /tmp/phantomjs
wget http://phantomjs.googlecode.com/files/phantomjs-2.1.1-linux-x86_64.tar.bz2
tar xf phantomjs-2.1.1-linux-x86_64.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 9: 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
user.global_admin = true

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 10: 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. Oder: Ctrl+C.

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 11: 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

Add a custom footer
Add a custom sidebar
Clone this wiki locally