iZivi ist ein Tool, um Schweizer Zivildienstleistende in einem Einsatzbetrieb zu verwalten.
| Name | Verwendung | Informationen / Tutorials |
|---|---|---|
| Ruby | Basis für das Backend | Basis Ruby-Tutorial |
| Javascript (ES6) | Basis für das Frontend | Basis-Tutorial von Mozilla Neue Funktionen in ES6 |
| Docker | Software-Virtualisierung, genutzt für die Entwicklung | Einführung in Docker Einführung in docker-compose |
| Git | Versionsverwaltung | Einführung in Git |
| Lokalise | Localization and translation management platform | Lokalise |
| Name | Verwendung | Informationen / Tutorials |
|---|---|---|
| Ruby on Rails | Ruby Web-Framework mit integriertem ORM. | Offizielle Dokumentation |
| RSpec | RSpec wird für das Testing von Ruby-Code verwendet. | RSpec tutorial |
| Name | Verwendung | Informationen / Tutorials |
|---|---|---|
| React | Javascript View-Library | Erforderliche JavaScript-Kenntnisse für React Offizielles Tutorial von React (eher oberflächlich und nicht als Einsteiger zu empfehlen!) Detaillierte Einführung in React React Lifecycle Cheetsheat |
| Yarn | Paketverwaltung und Entwicklungsserver ($yarn run watch) | Yarn vs. NPM Offizielle Website von Yarn |
| Babel | Bibliothek zur Bereitstellung von JavaScript ES6-Funktionen in älteren Browsern | Was ist Babel? |
| Webpack | Bundeling JS, CSS, SASS modules | Einführung in Webpack (komplex!) |
| IZI Toast | Snackbar for Error and Feedback | Offizielle Webseite |
Es gibt mehrere Umgebungen, welche auf dem SWO server laufen. We have multiple environments running on the stiftungswo.ch server.
| URL | Type | Usage |
|---|---|---|
| https://izivi-api.stiftungswo.ch | Production (Reflects "master" branch) | This is the live version of the app which is used by Zivis/SWO Employees |
| https://izivi-api-develop.stiftungswo.ch | Staging (Reflects "develop" branch) | This version reflects the latest development progress and can be used to show new features or test |
| https://izivi-api-test.stiftungswo.ch | Testing (Reflects no branch specifically. Can only be deployed by pushing to the bare testing repository) | This version is used to test features/code, which is not yet ready to release to staging. |
Die production sowie die staging Umgebung werden ausschliesslich durch ein automatisches Deployment, welches Semaphore macht, released.
Einzig die testing Umgebung muss manuell released werden.
Zivis können Ihre Informationen über den Menupunkt „Profil“ anpassen. Admins können alle Profile anpassen (Menupunkt „Mitarbeiterliste“) und haben zusätzlich die Möglichkeit, interne Bemerkungen zu schreiben und Benutzerrollen anzupassen.
Hier werden alle Einsätze aufgeführt, die einem Pflichtenheft sowie einem Zivi zugeteilt wurden.
Es gibt zusätzlich die Service Overview, in welcher man pro Jahr sehen kann, welche Zivis wann einen Einsatz haben.
Das ExpenseSheet sind die Spesenblätter. Anhand der geleisteten Tage, Ferien etc. werden die fälligen Spesen pro Monat gerechnet. Die Spesenblätter kann jeder Zivi in seinem Profil anschauen sowie den Stand der Bearbeitung.
D: Ende jedes Einsatzes sollte ein automatisiertes Mail an alle Abschliessenden Zivis versandt werden, welche eine Umfrage zur Zufriedenheit ausfüllen können. Diese Auswertung hilft dem Einsatzbetrieb Unzufriedenheiten zu erkennen und frühzeitig verbesserungsmassnahmen zu erkennen.
E: By the end of every operation should an email be sent to the person who absolves the community servicce. This email contains a link to a survey which helps the company to detect problems early and increase the happiness of the staff.
D: Die Mitarbeiterliste Zeigt eine Übersicht über alle Zivis und Mitarbeiter welche am izivi registriert sind sowie deren Einsatzdauer an. Hier können die Personen auch gelöscht oder inaktiv geschaltet werden.
E: The staff-list shows an overview over all community-workers and SWO-stuff which is registered at the izivi. It also shows the duration of the service. These users can be marked inactive or be deleted.
D: Die Telefonliste generiert in einem Ausgewählten Zeitraum eine Informationsliste aller Zivis welche in diesem Zeitraum einen Einsatz haben. Die Liste beinhaltet: Nachname, Vorname, Adresse, PLZ / Ort, Telefonnummer, Email.
E: The phone-list generates a PDF in a selected time period from all community-workers. The PDF contains the following informations: Surname, Prename, Address, Town, Phonenumber, Email.
D: Das Pflichtenheft beinhaltet die Pflichtenhefter der SWO. Die dazugehörigen Spesen wie auch IDs und Aktivierung.
E: The dutybook contains all dutybooks for the SWO. It defines the expenses and activations.
D: Die Freitage definieren die Feiertage wie auch Geschäftliche Freitage an welchen nicht gearbeitet werden muss.
E: In the holidays-view are the holidays and the business-holidays defined which are work-free.
D: Die Planung zeigt eine Übersicht über die Zivildienstleistenden und deren Einsatzdauer.
E: The scheduling shows an overview of the community-workers and their schedule.
D: Die Spesen zeigt die Spesenblätter der Zivildienstleistenden zugehörig zu den Monatlichen Spesenblättern. Zusätzlich kann eine Spesenstatistik generiert werden, welche den Abgleich mit den Zahlungen des Bundes vereinfacht.
E: The expenses shows the expense-sheets of the community-workers accordingly to the monthly expense-papers. Additionally there is a expense statistics which can be genereated which is used for comparison wich the payments of the federation.
D: Die Auszahlungen vereint die Spesen in einer Zahlungsabwicklung. Es kann ein XML exportiert werden, welche direkt ins e-banking eingelesen werden kann.
E: The payments contains the expenses in a payment-schedule. An XML can be generated which contains all informations for a ebanking-payment-import.
Wenn Docker noch nicht installiert: z.B hier herunterladen. Wichtig: Auf Linux muss docker-compose noch separat installiert werden.
- Repo clonen und im neuen Verzeichnis wechseln
- Dort
docker-compose upausführen - Das Terminal des API-containers starten mit
docker exec -it better_izivi_api bashin ein neues CLI-Fenster oder über die UI. - Dort
rails db:create,rails db:migrateundrails db:seedausführen (Zwei neue Datenbanken werden erschaffen und mit Daten gespiesen.) - Jetzt ist die Anmeldung mit diesen Zugangsdaten im Frontend möglich.
Fast jede Linux-Distribution wird mit einem Paketmanager ausgeliefert. Diese ermöglichen dir, bequem neue Programme zu installieren, ohne dazu eine aufwendige Installation durchführen zu müssen. Unter Mac hat die Community homebrew entwickelt, um einen solchen Paketmanager auf Mac bereitzustellen.
Die Installation kann im Terminal mit einem Einzeiler angestossen werden, welcher sich auf der offiziellen Website befindet.
Ruby wird einfacherweise mit rbenv installiert:
brew install rbenv ruby-buildecho 'eval "$(rbenv init -)"' >> ~/.bash_profilesource ~/.bash_profilecd better-izivi/api/rbenv installgem install bundler
- Ins Verzeichnis des betterIzivi wechseln (z.B. cd
~/src/swo/better-izivi/api) - Die .env-Datei kopieren
cp .env.example .env - Die .env-Datei ausfüllen
bin/setupausführen, oder falls ein Docker container zur Entwicklung verwendet wird:docker run -it [docker-container-name] api/bin/setup- Die API ist nun unter
localhost:28000erreichbar.
Um das iZivi in verschiedenen Sprachen zu übersetzen, wurden alle Strings der Applikation durch Keys ersetzt. Für jede Sprache gibt es ein oder mehrere JSON-Files mit allen Keys und der entsprechenden Übersetzung. Diese Files sind im GitHub-Repository eingecheckt. Gleichzeitig sind die Übersetzungen auf die Internationalisierung Plattform Lokalise synchronisiert. Dort können sie übersichtlich verwaltet, und auch automatisiert übersetzt werden. Im root Verzeichnis vom iZivi befinden sich zwei bash scripts (lokalise-upload und lokalise-download) mit denen die Übersetzungen hoch- und runtergeladen werden können. Dies muss im Moment noch manuell von dem Entwickler gemacht werden.
- Lokalise CLI tool installieren: Lokalise CLI
- Ruby i18n-task installieren:
gem install i18n-tasks - Die lokalise.yml Datei kopieren
cp lokalise.example.yml lokalise.yml - lokalise.yml Datei ausfüllen mit den Lokalise Credentials (KeePass)
- Ruby installieren mit Rubyinstaller mit devkit (installiert gem)
- Yarn installieren
- Installation mysql-Server
- Repo klonen
- Im Ordner frontend
yarnausführen (installiert Frontend dependencies) - im Ordner api
gem install bundlerausführen (installiert gems)
- Im Ordner frontend
- Das configfile anpassen und die Ports im frontend von 28000 auf 3000 wechseln (lokaler API port)
- Aus Ordner api, Datenbank installieren mit
rails db:create db:migrate
- Server starten
- API: Ordner api:
rails s - Frontend: Ordner frontend,
yarn start(Meldung zu Portänderung bejahen)
- API: Ordner api:
- Linter ausführen im jeweiligen Ordner:
rubocop -a(korrigiert auch direkt Fehler) - Rspec einzelnes File:
bundle exec rspec ./spec/services/pdfs/expenses_overview_service_spec.rb - Rspec alle Tests:
bundle exec rspec
Wenn man vom vom 'develop' Branch in dem 'master' Branch mergen will, empfiehlt es sich, git merge --ff-only develop zu benutzen. So entsteht kein Merge-Commit. Wenn man das nicht macht, erscheint folgende Nachricht auf github.com beim 'master' Branch.
RubyMine ist eine IDE für Ruby von Jetbrains. Will man mit RubyMine im Docker entwickeln und testen, muss jedoch noch einiges konfiguriert werden:
- In RubyMine:
Preferences > Languages & Frameworks > Ruby SDK and Gemseine neue Remote SDK hinzufügen (+ > New remote...) Docker Composeauswählen- Bei
Configuration filedie Semaphore-Docker-Compose-Datei auswählen (better-izivi/docker-compose.semaphore.yaml) - Die
system environment variables(Icon rechts beiEnvironment variables) deaktivieren
Nun kann man direkt in RubyMine die API starten und beenden. (Über Edit run configurations das Port-Mapping anpassen)
Das Backend und Frontend sollen immer sauber formatiert sein (wird von der CI überprüft).
Vor dem Commiten sollten immer die Formatier-Tools ausgeführt werden.
- Backend:
docker exec better_izivi_api rubocop -aoderbundle exec rubocop -a, falls nativ entwicklet wird - Frontend:
docker exec better_izivi_frontend yarn format, bzw. nuryarn run format
Für das Backend kommt rubocop zum Einsatz und für das Frontend übernimmt TSLint den Job.
Semaphore kann das Projekt zu einem beliebigen remote host deployen. Für das deployment auf dem swo server wird das hauseigene server-apps verwendet.
Fehler auf Produktivsystemen werden auf Sentry geloggt wenn eine valide SENTRY_DSN gesetzt ist. Siehe Config
Die Variablen werden im Travis Build abgefüllt.
Weitere Informationen im [privaten Wiki] (https://wiki.stiftungswo.ch/it:sw:izivi#deployment)
Um Logs auszugeben, kann der Rails Logger verwendet werden (z.B. Rails.logger.info "Your message"). Die Logs werden nach api/logs/ geschrieben. Dieser Ordner wird zwischen dem Docker Container und deiner lokalen Maschine synchronisiert.
Das Projekt enthält das standardmässige ActiveRecord ORM. Mehr infos unter https://www.rubydoc.info/gems/activerecord
- Korrektes remote auf dem lokalen System hinzufügen: bspw.
git remote add metanet-test swo@stiftungswo.ch:~/git/better-izivi/test.git git push -f metanet-test [DEIN BRANCH, DER DEPLOYED WERDEN SOLL]:masterausführen.
Achtung: MASTER (izivi.stiftungswo.ch) UND DEVELOP (izivi-develop.stiftungswo.ch) SOLLTEN NIE MANUELL DEPLOYED WERDEN. BEIDE APPLIKATIONEN WERDEN DEPLOYED, IN DEM MAN EINEN PULL REQUEST IN DAS JEWEILIGE ENVIRONMENT MERGED UND SEMAPHORE DIES DANN AUTOMATISCH DEPLOYED.
Nur iZivi testing (izivi-test.stiftungswo.ch) sollte manuell deployed werden!
Wenn das deployment erfolgreich war, kommt eine Slack message in dem entsprechenden Channel (#better-izivi).
Seit React 16.5 gibt es einen Profiler, mit welchem die Ladezeiten der einzelnen Komponenten angezeigt werden kann. Dazu die React Dev-Tools in Chrome installieren und die Chrome-Konsole öffnen. Zum React-Tab wechseln, dort auf "Profiler" klicken und auf den Record-Button drücken.
Anschliessend kann die Seite neu geladen werden und der Record-Button erneut gedrückt werden, um die Aufzeichnung zu beenden. nun hat man eine detaillierte Ansicht aller Ladezeiten der Komponenten.
Ein Servercrash führt vielleicht zu fehlerhaften Dockerstarts. Dies kann vielleicht durch einen Push auf den Master gefixt werden.
iZivi is licensed under the GNU Lesser General Public License v3.0 (LGPLv3). LICENSE