eAppointment Docs

English

Deutsch

English

Deutsch

Appearance

Devcontainer and Podman ​

Local development uses Podman with Dev Containers. Start the stack with:

bash
devcontainer up --workspace-folder .

This creates and starts the local container setup used for development and testing. It also auto-detects your host architecture (amd64 vs arm64) and pulls the matching local PHP base image tag for zms-web.

To wipe Podman completely on the host and recreate the stack, see Quick reset of the local environment.

On macOS, see Podman and Dev Containers on macOS.

Containers and local endpoints ​

The following local containers are automatically created when running devcontainer up --workspace-folder .:

  • zms-web (pre-built local PHP base image), app endpoint: http://localhost:8090
  • zms-refarch-gateway (local RefArch API gateway), endpoint: http://localhost:8084
  • zms-keycloak (same Keycloak image family as RefArch setup), endpoint: http://localhost:8080/auth
  • zms-db (MariaDB), DB port: 3306
  • zms-phpmyadmin, endpoint: http://localhost:8036
  • zms-citizenview, Vite hot reload endpoint: http://localhost:8082
  • zms-mail-viewer, local outbound mail queue viewer: http://localhost:8025 (login superuser / vorschau)

Local mail queue viewer ​

ZMS stores outbound mails in the API queue (GET /api/2/mails/) before zmsmessaging sends them. In local dev SMTP is usually disabled, so mails stay in the queue.

The zms-mail-viewer sidecar polls that API and shows subject, recipient, HTML preview, and plain text. It runs only in the local Dev Container setup.

  • URL: http://localhost:8025
  • Login: superuser / vorschau (browser basic auth; configurable via ZMS_MAIL_VIEWER_USER / ZMS_MAIL_VIEWER_PASSWORD)
  • API auth: local superuser credentials via ZMS_MAIL_VIEWER_API_USER / ZMS_MAIL_VIEWER_API_PASSWORD (default superuser / vorschau)

Automatic setup on startup ​

During local startup, the environment also prepares the main development flow:

  • runs composer install, npm install, and npm build in zms-web
  • sets up and launches zmscitizenview in a local container zms-citizenview with npm install and npm run dev dependencies and starts hot reload on localhost:8082
  • installs browser automation tooling in zms-web for local zmsautomation runs (Firefox/Xvfb plus WebDriver support for Chrome/Chromium, Edge, and Firefox via chromedriver, msedgedriver, and geckodriver)

This means devcontainer up --workspace-folder . already includes the install/build/bootstrap flow, including ./cli db full-setup.

You can still rerun module dependency/build commands at any time:

bash
podman exec -it zms-web bash -lc "./cli modules loop composer install"
podman exec -it zms-web bash -lc "./cli modules loop npm install"
podman exec -it zms-web bash -lc "./cli modules loop npm build"

Database initialization (./cli db full-setup) ​

The local setup runs ./cli db full-setup, which:

  • imports the base DB from .resources/zms.sql
  • imports DLDB offices/services via hourly cronjob flow
  • imports production-like test data from zmsautomation Flyway migrations
  • runs database migrations
  • runs the minutly cronjob to generate opening-hours-related test data

You can rerun full setup at any time:

bash
podman exec -it zms-web bash -lc "./cli db full-setup"

For Keycloak host mapping and Linux Podman notes, see Local Keycloak Setup.