MILA Mitgliederplattform

Member plattform of MILA Mitmach-Supermarkt e.G..

Local development setup

• Install Docker, nodejs, and PNPM. To do so, it is advisable to install Docker and nvm from your operating system's package repository and then: nvm install node and npm install -g pnpm

• Clone this repository

• Create .env files:

  cp .env.example .env
  cp collectivo/.env.example collectivo/.env

• Start the containers and wait for directus to be ready:

  docker compose up --wait

• Give directus access to directories (runs as user node):

  docker compose exec -u root directus-dev chown -R node:node /directus/extensions /directus/uploads

• Apply data schema:

  npx directus-sync push

• Install packages and start collectivo:

  pnpm i
  pnpm dev

• Go to http://localhost:3000 and click on "Seed Example Data" (fast, small dataset) or run pnpm seed

  • For a production-scale dataset, click "Seed Full Dataset" instead - this takes a few minutes

The following services will then be available:

• Frontend http://localhost:3000
• Directus http://localhost:8055

Test users for frontend and directus (after seeding):

• [email protected] / admin
• [email protected] / editor
• [email protected] / user

Login credentials for directus admin without keycloak:

• Username [email protected]
• Password admin

Troubleshooting

• Resetting everything
  • Delete .env and collectivo/.env
  • To be super clean, also delete node_modules, collectivo/node_modules, and collectivo/.nuxt
  • Run docker compose down -v

Testing

To run end-to-end tests, run npx cypress open or npx cypress run

Database schemas

Collectivo uses directus-sync to apply the database schema.

Updating the database schema

• Make changes to the database schema on your local system
• Update the database schema in the repository

  npx directus-sync pull && node sort-directus-config.mjs

• Make a database backup of the production system (see below)
• Run

  npx directus-sync push

  (credentials will be taken from .env)

Troubleshooting

• Changing the directus version also changes the schema. Pull the schema after changing the version and starting the container.
• Changing flows often creates errors on push, this can be solved by deleting the changed flows manually before pushing.
• When changing the directus version, push the schema first, then change the directus version, and then pull the schema again.

Database backups

Database backups are not managed by Docker Compose. The Directus database is an external PostgreSQL instance; backups must be handled by the database host provider or a separate backup tool.

For local development, you can create a manual backup of directus-db-dev:

docker compose exec directus-db-dev pg_dump --clean -U directus directus > my-backup.sql

To restore it:

docker compose exec -T directus-db-dev psql -U directus -d directus < my-backup.sql

To reset the dev database before restoring (this will delete all data):

docker compose down -v
docker compose up --wait directus-db-dev
# wait for healthy, then restore

Local setup with Keycloak

The dev setup runs without keycloak. To test keycloak integration:

• In .env, set

  COMPOSE_PROFILES = "dev,keycloak"
  DIRECTUS_AUTH_PROVIDERS = "keycloak"
  

• In collectivo/.env, set

  NUXT_PUBLIC_USE_KEYCLOAK = "true"
  

• Add the following to your /etc/hosts file (here is a guide): 127.0.0.1 keycloak (required so your browser uses the same hostname as Docker internally, which must match the issuer embedded in Keycloak's tokens)
• Open the Keycloak admin UI at keycloak:8080/admin.
• Login with [email protected] / admin (user in the "master" realm provisioned by KC_BOOTSTRAP_ADMIN_USERNAME/PASSWORD)
• To use directus with keycloak
  • Make sure collectivo is running (pnpm dev)
  • Login with [email protected] / admin (user in the collectivo realm). Directus provisions a user but denies access to admin interface.
  • Click "Change user" and log in to [email protected] / admin (not through keycloak).
  • From the user directory on the sidebar, find [email protected] and set role > admin.

The collectivo realm contains users with kc prefix to avoid conflicts with the users already seeded in directus:

• [email protected] / admin
• [email protected] / editor
• [email protected] / user

For more details see the Keycloak readme.

Local setup with Nextcloud

• In .env, set COMPOSE_PROFILES = "dev,keycloak,nextcloud". Nextcloud depends on the keycloak profile.
• Open the Nextcloud GUI at localhost:8081 and create an admin user to finish the installation.

For setup of the integration with keycloak see the Nextcloud readme.

Production setup

• Install Docker and PNPM
• Create a sync lock file "/directus/uploads/sync.lock"
• Provision an external PostgreSQL database (with PostGIS extension) for Directus
• Provision an external MariaDB database for Habidat
• Provision an external PostgreSQL database for Keycloak
• Set .env vars
  • Generate secure secrets, keys, and passwords
  • Set DIRECTUS_DB_HOST to the hostname of the external Directus database
  • Set HABIDAT_DB_HOST to the hostname of the external Habidat database
  • Set KEYCLOAK_DB_HOST to the hostname of the external Keycloak database
  • Remove variable KEYCLOAK_COMMAND (absence triggers production mode)
• Set up a reverse proxy with a docker network called proxiable
• Set the following custom Nginx configuration for Keycloak

  proxy_buffer_size   128k;
  proxy_buffers   4 256k;
  proxy_busy_buffers_size   256k;
  

• Clone this repository
• Run pnpm i and pnpm build
• Run docker compose -f docker-compose.production.yml up -d

Server updates

For deploying updates on the server:

• Create a database backup (see above)
• Run git pull
• Optional: if the directus version changed, perform the upgrade on the running server:
  • Build the new version: docker compose -f docker-compose.production.yml build directus
  • Run the new version: docker compose -f docker-compose.production.yml up -d directus
• Optional: Run pnpm i
• Run pnpm build
• Optional: If the environment configuration in .env or the docker compose file changed: Run docker compose -f docker-compose.production.yml up -d collectivo
• Run docker compose -f docker-compose.production.yml restart collectivo
• Optional: Apply database schema changes (see above)