Development install on linux

English

(deutsche Übersetzung weiter unten)

Here we show you how you can install eCamp v3 on your computer for development.

If you only want to use eCamp, we strongly recommend to use the official version, or use the old version on https://ecamp.pfadiluzern.ch.

In case you have problems during the installation, something doesn't work or you need further assistance or explanations, feel free to open a discussion on GitHub.

Preparation

In order to run eCamp v3 on your computer, you only need Docker (including docker compose) and git.

Docker is a tool which helps to run software on different computers. In so-called Docker containers, we can define which preliminary software and system settings are available, and run eCamp v3 everywhere with the same preconditions. This way we e.g. do not have to care about which version of PHP is installed on our computers, because the correct version is installed inside the container.

In order to download the publicly available source code of eCamp v3 onto your computer, we use the tool git. Git helps us not to lose track when we change and improve the code and always keeps backups of all versions.

Guides to install git on Linux, Mac OS and Windows are available here: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

For Docker (and the included tool docker compose), you can follow this guide: https://docs.docker.com/engine/install/#server. We recommend not to install Docker Desktop on Linux, but install only the Docker Engine (the server version), because Docker Desktop on Linux runs inside a VM which slows things down, had permission issues and was not stable in our tests (as of March 2023). If you already have Docker Desktop installed on Linux and are running into issues, you can try to exit Docker Desktop before starting eCamp v3. Docker should then revert to only using the Docker Engine part of your Docker Desktop installation.

⚠️ If you have followed our recommendation and installed Docker Engine on Linux, make sure to also follow the post-installation steps so you can run docker commands without being root (without sudo).

Once you have these two requirements, we can install eCamp v3 itself. That is, we will download the source code from the internet (GitHub) using git, and run the Docker containers which are defined in the source code.

eCamp v3 source code

The eCamp v3 source code resides on GitHub. In order to download the files onto your computer, you have to clone the git repository of eCamp v3.

This can be done using the following command, if you are working on the console:

git clone https://github.com/ecamp/ecamp3.git && cd ecamp3

💡 This command will download the code to your machine. If you plan on making changes to the code and contributing them back, please also follow the git setup instructions in CONTRIBUTING.md.

Start the Docker containers

The ecamp3 repository contains a docker-compose.yml file, which describes all the Docker containers needed for running eCamp v3.

You can install and start the application using a single command:

docker compose up

This requires an internet connection and can take several minutes, because all third-party software which eCamp v3 relies on needs to be downloaded. Once things have settled down, eCamp v3 is running on your computer. You can visit http://localhost:3000, register or log in using the automatically created user [email protected] / test. The backend, which retrieves data for the website from the database, can be found at http://localhost:3000/api. Emails which your local eCamp v3 copy sends are not really delivered, but are instead collected in MailHog at http://localhost:3000/mail.

Congratulations, you did it!

Using composer and npm

For the installation and management of required third-party software, eCamp v3 uses composer in the backend and npm in the frontend. During development, it sometimes is necessary to update or install third-party software. To do this, we have to work with composer and npm inside the containers. This can look as follows:

docker compose exec php composer update
docker compose exec frontend npm update

The tools basically work exactly the same as if we had installed them outside of the container, except that the command has to be sent inside of a container (using docker compose exec <service-name>). This way we can make sure that all developers use the same exact versions of composer and npm.

VS Code

In case you want to use VS Code as your editor, we have collected some information on that in the wiki.

Deutsch

Hier zeigen wir dir, wie du eCamp v3 für die Entwicklung auf deinem Computer installieren kannst.

Wenn du eCamp einfach nur nutzen willst, dann empfehlen wir dir dringend die bereits laufende Version auf https://app.ecamp3.ch oder die alte Version auf https://ecamp.pfadiluzern.ch zu verwenden.

Falls du bei der Installation auf Probleme stösst, etwas nicht funktioniert oder du weitere Unterstützung oder Erklärungen benötigst, eröffne eine Discussion auf GitHub.

Vorbereitung

Um eCamp v3 bei dir laufen zu lassen musst du nur Docker (inklusive docker compose) und Git auf deinem Computer haben.

Docker ist ein Tool, das dabei hilft, die gleiche Software auf ganz verschiedenen Computern laufen zu lassen. In sogenannten Docker containers kann man genau definieren, welche Software und Systemeinstellungen verfügbar sind und eCamp v3 so überall mit den gleichen Voraussetzungen laufen lassen. So müssen wir uns z.B. nicht darum kümmern, ob PHP auf unseren Computern installiert ist und in welcher Version, denn die korrekte PHP-Version ist im container installiert.

Um den öffentlich verfügbaren Programmcode von eCamp v3 auf deinen Computer herunterzuladen, brauchen wir das Tool Git. Git hilft uns dabei, wenn wir den Code ändern und verbessern, den Überblick nicht zu verlieren und behält immer Backups von allen Versionen.

Anleitungen um Git auf Linux, Mac OS und Windows zu installieren findest du hier: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git

Für Docker (und das dazugehörige Tool docker compose) kannst du dieser Anleitung folgen: https://docs.docker.com/engine/install/#server. Wir empfehlen, nicht Docker Desktop auf Linux zu verwenden, sondern Docker Engine (die Server-Version). Grund ist, dass Docker Desktop auf Linux in einer VM läuft, was das Ganze deutlich langsamer macht, Berechtigungsprobleme mitbringt und in unseren Tests im März 2023 nicht stabil lief. Falls du bereits Docker Desktop auf deinem Linux installiert hast, kannst du versuchen, Docker Desktop zu beenden bevor du eCamp v3 startest. Docker müsste dann auf den Docker Engine Teil zurückfallen.

⚠️ Falls du unserer Empfehlung gefolgt bist und Docker Engine auf Linux installiert hast, vergiss nicht die Post-Installations-Schritte auszuführen, sodass du docker Befehle ausführen kannst ohne Root zu sein (also ohne sudo).

Wenn du diese beiden Voraussetzungen hast, können wir eCamp v3 selber installieren. Das heisst, wir laden den Quellcode mithilfe von Git aus dem Internet (GitHub) herunter und lassen die darin definierten Docker container laufen.

eCamp v3 Quellcode

Der eCamp v3 Programmcode liegt auf GitHub. Damit du die Dateien auf deinen Rechner heruntergeladen bekommst, musst du das Git-Repository von eCamp v3 klonen.

Der entsprechende Befehl, falls du auf der Konsole arbeitest, sieht so aus:

git clone https://github.com/ecamp/ecamp3.git && cd ecamp3

💡 Dieser Befehl lädt den Code auf deinen Computer herunter. Falls du vorhast, später auch mal Code-Änderungen zu contributen, befolge bitte zudem die Anleitung "Git einrichten" im CONTRIBUTING_DE.md.

Docker container starten

Das ecamp3 Repository enthält ein docker-compose.yml File, welches die benötigten Docker containers beschreibt.

Du kannst die ganze Applikation mit einem Befehl installieren und starten:

docker compose up

Das braucht eine Internetverbindung und kann einige Minuten dauern, da alle Software von anderen Herstellern die eCamp v3 benötigt noch heruntergeladen werden muss. Wenn sich das ganze beruhigt hat, läuft eCamp v3 auf deinem Computer. Du kannst es unter http://localhost:3000 aufrufen, dich registrieren oder dich mit dem automatisch erstellten User [email protected] / test einloggen. Das Backend, welches die Daten für die Webseite aus der Datenbank holt, kannst du unter http://localhost:3000/api anschauen. E-Mails, welche dein lokales eCamp v3 versendet, werden nicht wirklich ausgeliefert, sondern landen alle im MailHog unter http://localhost:3000/mail.

Gratuliere. Du hast es geschafft!

Composer und NPM bedienen

Für die Installation und Verwaltung von benötigter Drittsoftware verwenden wir in eCamp v3 im Backend Composer und im Frontend NPM. Während der Entwicklung muss man manchmal Drittsoftware updaten oder neu installieren. Dafür muss man Composer und NPM in den Containern bedienen. Dies sieht z.B. so aus:

docker compose exec php composer update
docker compose exec frontend npm update

Die Tools funktionieren also grundsätzlich genau gleich wie wenn man sie ausserhalb des Containers installiert hat, nur dass man den Befehl in einen Container hinein absetzen muss (mit docker compose exec <service-name>). So stellen wir sicher, dass wir alle beim Entwickeln dieselben Versionen von composer und npm verwenden.

VS Code

Falls du VS Code als deinen Editor einsetzen möchtest, haben wir ein paar Informationen dazu im wiki zusammengetragen (nur englisch).