Skip to content

Getting Started

Jump to bottom Edit New page
Sebastian Fiedlschuster edited this page Sep 13, 2019 · 68 revisions

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

Betriebsystem:

Einführungs-Video

https://www.youtube.com/watch?v=SloUmkLRXcI

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.

Die beiden Haupt-Repositories fügt man als Upstream-Remotes hinzu:

# bash
cd ~/rails/wingolfsplattform
git remote add upstream [email protected]:fiedl/wingolfsplattform.git

cd ~/rails/your_platform
git remote add upstream [email protected]:fiedl/your_platform.git

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 apt install docker.io docker-compose

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.

Als Orchestrierungswerkzeug verwenden wir Docker-Compose. Wenn die oben installierte Version zu alt sein sollte, kann man wie folgt eine neuere nachinstallieren:

# bash
docker-compose --version

sudo curl -o /usr/local/bin/docker-compose -L "https://github.com/docker/compose/releases/download/1.15.0/docker-compose-$(uname -s)-$(uname -m)"
sudo chmod +x /usr/local/bin/docker-compose

Quelle: https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-16-04

Schritt 6: Datenbanken

Installation von MySQL

# bash
sudo apt install mysql-server 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:

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 install redis-server

Neo4j-Datenbank

Als Graph-Datenbank verwenden wir Neo4j.

Neo4j betreiben wir als Docker-Container, sodass Neo4j nicht manuell installiert und eingerichtet werden muss, sondern lediglich das Repository mit der entsprechenden Konfiguration geklont werden muss:

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

Damit kann Neo4j dann gestartet werden, am Besten in einem separaten Terminal-Tab.

# bash
cd ~/rails/wingolfsplattform-docker
docker-compose up wingolfsplattform_neo4j wingolfsplattform_neo4j_test

Durch das obige Kommando werden zwei Neo4j-Datenbank-Services gestartet, einer für die Entwicklungsumgebung und einer für die automatisierten Tests.

Testhalber kann http://localhost:7474/ im Browser öffnen (Benutzer: neo4j, Passwort: trinity), um sich die (noch leere) Graph-Datenbank anzusehen.

Damit auch die Plattform weiß, wie sie sich zu Neo4j verbinden soll, müssen noch zwei Umgebungsvariablen gesetzt werden:

# bash
echo 'export NEO4J_REST_URL_TEST="http://neo4j:trinity@localhost:7475/"' >> ~/.bashrc
echo 'export NEO4J_REST_URL="http://neo4j:trinity@localhost:7474/"' >> ~/.bashrc

Schritt 7: Ruby-Pakete

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

NodeJS installieren:

# bash
sudo apt install build-essential libssl-dev
curl -sL https://deb.nodesource.com/setup_7.x | sudo bash
sudo apt install nodejs
node --version

Node-Package-Manager installieren:

# bash
sudo apt install npm

Yarn installieren:

# bash
npm i -g yarn

Danach mit Yarn und Webpack die benötigten JavaScript-Bibliotheken installieren:

# bash
cd ~/rails/your_platform
yarn install
bin/pack

Schritt 8: Secrets

Geheime Informationen wie SMTP-Passwörter, API-Schlüssel zu externen Anwendungen werden in config/secrets.yml gespeichert. Für die lokale Entwicklungsumgebung braucht man nur einen Schlüssel, nämlich secret_key_base, das zur Verschlüsselung verwendet wird.

Man braucht zwei Schlüssel: Einen für die Entwicklungsumgebung, einen für die Test-Umgebung. Einfach mit pwgen 100 erstellen.

Die beiden Schlüssel fügt man dann in die Datei config/secrets.yml ein:

# ~/rails/wingolfsplattform/config/secrets.yml

development:
  secret_key_base: your-secret-key-base-for-development-here

test:
  secret_key_base: your-secret-key-base-for-testing-here

Schritt 9: Automatisierte Tests

SQL-Datenbanken erstellen

# bash
cd ~/rails/wingolfsplattform

# create database
bin/rails db:create db:migrate db:test:prepare

Gecko-Treiber installieren

Um in den automatischen Tests mit dem Browser zu interagieren, verwenden wir den Firefox-Gecko-Treiber:

# bash
curl -L https://github.com/mozilla/geckodriver/releases/download/v0.19.1/geckodriver-v0.19.1-linux64.tar.gz | tar -xz
sudo mv geckodriver /usr/local/bin/

Tests laufen lassen

# bash
cd ~/rails/wingolfsplattform
bin/rspec

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

Schritt 10: Anwendung im Browser öffnen

Server starten

# bash
cd ~/rails/wingolfsplattform
bin/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.

Schritt 11: Rails-Console

Mit Hilfe der Rails-Console kann man auf den Model-Layer der Plattform zugreifen, ohne die Benutzeroberfläche zu verwenden.

cd ~/rails/wingolfsplattform
bin/rails console

Beispiel: Anzahl der Benutzer abfragen

# rails console
User.all.count

Beispiel: E-Mail-Adresse ändern

# rails console
user = User.first
user.email = "[email protected]"
user.save

Schritt 12: 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
cd ~/rails/wingolfsplattform
foreman start  # Worker starten
foreman stop   # Worker ausschalten. Oder: Ctrl+C.

Schritt 13: Kleine Helferlein

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/your_platform'

Editor-Einstellungen

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