Development install on linux

English

(deutsche Übersetzung weiter unten)

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

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

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 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 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 to keep Um den öffentlich verfügbaren Programmcode von eCamp v3 auf deinen Computer herunterzuladen, brauchen wir das 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. 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 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 source code

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

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

Start the Docker containers

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

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 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 für die Entwicklung auf deinem Computer installieren kannst.

Wenn du eCamp einfach nur nutzen willst, dann empfehlen wir dir dringend die bereits installierte Version auf https://ecamp.pfadiluzern.ch zu verwenden, oder dich für Zugang zur geschlossenen Beta-Version zu bewerben.

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 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 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 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 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-Quellcode

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

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

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

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 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).