Skip to content

development-setup.md

Latest commit

 

History

History
274 lines (209 loc) · 11.3 KB

development-setup.md

File metadata and controls

274 lines (209 loc) · 11.3 KB

Development Setup

Contents

Prerequisites

  • JDK 25: for running the backend and the Android version of the frontend. We use Eclipse Temurin, but others might work as well.

  • fvm >= 4.0.1: managing Dart and Flutter versions.

  • Node.js >= 24.x.x: to develop the administration web application.

  • One of:

    • Docker >= 4.5.0: for running the various backend services.
    • Podman >= 5.6.2 (experimental).

  • For developing and building the iOS version of the mobile app (macOS required):

    • brew package manager for macOS. Optional but highly recommended.
    • XCode >= 16.4
    • Ruby >= 3.4.7
    • Bundler >= 2.7: for installing cocoapods and other dependencies.
    • cocoapods >= 1.16.2: for installing the iOS dependencies.

  • For developing and building the Android version of the mobile app:

    One of:

Recommended IDEs:

Auxiliary Services

[!NOTE]: all commands here are meant to be executed in the project root directory.

If you want to develop or test against a local backend, you need to start some auxiliary services. You can either use the open-source Podman/Podman Compose or classic Docker/Docker Compose.

  • When using Podman, initialize and start the machine:

    podman machine init
podman machine start

  • Start auxiliary backend services:

    • When using Podman: podman compose up -d
    • When using Docker: docker compose up -d

Frontend

[!NOTE]: all commands here are meant to be executed in the /frontend directory.

Frontend Setup

  • Install flutter dependencies: fvm flutter pub get

  • When using IntelliJ, open the settings and

    • Install the Dart plugin and set the Dart SDK path
    • Install the Flutter plugin and set the Flutter SDK path

    Note: IntelliJ needs access to environment variables to run these commands successfully.

Android

  • When using IntelliJ, install the Android plugin.
  • Install the Android SDK.
  • Set the Android SDK path in the IntelliJ settings.

iOS

  • Install gems: cd ios && bundle install
  • Install cocoapods: cd ios && bundle exec pod install --repo-update
  • Optional: install cocoapods globally (only necessary if using IntelliJ run configurations to run on iOS): brew install cocoapods

Run Frontend

  1. Forward ports. As there are several services running and interacting, some ports need to be forwarded. This includes the backend port 8000 and the map tiles port at 5002. The command has to be run every time a device is connected.
adb reverse tcp:8081 tcp:8081 && adb reverse tcp:8000 tcp:8000 && adb reverse tcp:5002 tcp:5002
  1. Run the app
    • Bayern: Run (env:local+buildConfig:bayern)
    • Nuernberg: Run (env:local+buildConfig:nuernberg)
    • Koblenz: Run (env:local+buildConfig:koblenz)

Administration

[!NOTE]: all commands here are meant to be executed in the /administration directory.

Administration Setup

Install Node.js dependencies: npm install

Run Administration

  • With the IntelliJ run configuration: run Start administration (env:local+buildConfig:all).
  • With a shell: npm run start

Run e2e-tests for Administration

  1. Run backend and start the administration.
  2. install supported browsers for Playwright: npx playwright install
  3. Run Playwright tests:
    • All tests: npm run test:e2e
    • You can run individual tests by npm run test:e2e [file name]

Backend

[!NOTE]: all commands here are meant to be executed in the /backend directory.

IntelliJ set up

Open the IntelliJ project structure dialog under /File/Project Structure… and set up the project SDK to a JDK 25 installation. If the JDK is not listed in the SDK drop down, you might need to set it up under Platform Settings/SDKs (in the same dialog) first. SDK/JDK setup

Backend Setup

  • Create a DB with some test data (Migrate DB)
    • With an IntelliJ run configuration: Backend commands / DB recreate
    • With a shell: ./gradlew run db-recreate

Run Backend

Start the backend service

  • Using IntelliJ run configuration: Run backend (env:local+buildConfig:all)
  • Using a shell: ./gradlew run --args="execute"

Optional Backend Setup

The following setup is only necessary if you work with the corresponding services.

Local Backend Configuration

The backend configuration file config.yml is checked in git and should therefore not be modified for development purposes. Instead, you can create your own local copy:

  1. Copy config.yml to /backend/src/main/resources/config.local.yml:

    cp backend/src/main/resources/config/config.yml backend/src/main/resources/config.local.yml

  2. Adjust config

    A development SMTP server is configured as a Docker service in the docker-compose.yml file. To use it, set the smtp config to the following values:

    smtp:
   host: localhost
   port: 5025
   username: maildev@localhost.local
   password: maildev

    The web UI is available at http://localhost:5026

Map Styles

  1. Clone the submodule inside backend/ehrenamtskarte-maplibre-style
  2. Initialize all submodules by running git submodule update --init --recursive in the root directory

Matomo

  1. Set up the matomo instance http://localhost:5003. The public version is available at https://matomo-entitlementcard.tuerantuer.org.
  2. Login with your user.
  3. Add a new website f.e. bavaria (if not already done).
  4. Create an access token and disable Only allow secure requests for local testing.
  5. Add your matomo config for each project as described in Local Backend Configuration

Example:

projects:
  - id: ...
    # ...
    matomo:
      siteId: 1
      url: http://localhost:5003/matomo.php
      accessToken: <matomo-access-token>
  1. Create a card and check the Dashboard of your website
  2. Here you find Events (card actions) and Searches (stores in the app)
  • Note: Before you find Events and Searches, the archiving cron job has to be run (scheduled every 5 minutes). Check your selected date filter if you can't find events or searches.

Troubleshooting:

  • If your matomo instance is corrupt, you can just delete config/config.ini.php in folder ( var/www/html)
  • If you cannot send data to matomo check that your access token accepts unsecure request and localhost:5003 was added to matomos trusted_hosts at /var/www/html/config/config.ini.php

Inspecting Services

Common development tasks

  • Run Ktlint diagnostic: ./gradlew ktlintCheck
  • Run Ktlint formatter: ./gradlew ktlintFormat
  • Run Detekt diagnostic: ./gradlew detekt

DB tasks

  • Clear the DB's contents: ./gradlew db-clear
  • Run all migrations: ./gradlew db-migrate
  • Import data from online stores: ./gradlew db-import
  • Load developer sample data: ./gradlew db-import-dev
  • Create a clean DB with sample data (all of the above steps): ./gradlew db-recreate
  • Dump the DB 
    docker exec -ti entitlementcard-db-1 pg_dump -c -U postgres ehrenamtskarte > dump-$(date +%F).sql
  • Copy the dump to your local machine: 
    rsync root@ehrenamtskarte.app:dump-2020-12-23.sql .
  • Restore the dump 
    docker exec -i entitlementcard-db-1 psql ehrenamtskarte postgres < dump-$(date +%F).sql

Using ehrenamtskarte.app as Database

ssh -L 5432:localhost:5432 -L 5001:localhost:5001 team@ehrenamtskarte.app

That way the Adminer and postgres will be available locally.
⚡