Ga naar hoofdinhoud

Conduction Development Environment

Shared Docker Compose setup for all ConductionNL Nextcloud app development. The compose file lives in this repository (.github/docker-compose.yml) and is used by all Conduction apps.

Prerequisites​

  • Docker and Docker Compose v2+

  • A PHP coverage driver. Install it once:

    sudo apt install php8.3-pcov # match your PHP; php -v tells you
    php -m | grep -E '^(pcov|xdebug)$' # must print something

    This is not only for coverage reports. phpunit.xml sets failOnRisky and beStrictAboutCoverageMetadata, and both are inert without a driver. A test that executes a class its @covers block does not name is risky, and risky is exit 1 in CI, where a driver is loaded. Without one locally the check cannot fire, composer check:strict passes, and the suite prints OK, but there were issues!, which reads like a pass to anyone looking at the summary line instead of the exit code.

    On 2026-09-10 that reddened every PHPUnit cell in two repos within the same hour, on development, for the same reason: dossiq's EngineTaskInboxTest executing EngineInboxQuery, and pipelinq's ConnectorEgressTest executing ConnectorSourceRegister. Neither author could have seen it. Adding a collaborator to an existing test is an ordinary edit that looks nothing like touching coverage metadata. See .github#746.

  • The workspace directory should contain all app repos as siblings of .github/:

    apps-extra/
    ├── .github/ ← this repo (contains docker-compose.yml)
    ├── openregister/
    ├── opencatalogi/
    ├── softwarecatalog/
    ├── nldesign/
    ├── launchpad/
    ├── docudesk/
    ├── procest/
    ├── pipelinq/
    ├── zaakafhandelapp/
    ├── larpingapp/
    └── ...

Quick Start​

# Start the core environment (db + nextcloud + n8n)
docker compose -f .github/docker-compose.yml up -d

# Nextcloud is available at http://localhost:8080
# Login: admin / admin

Profiles​

The compose file uses Docker profiles to organize optional services. Only the core services (db, nextcloud, exapp-n8n) start by default.

Starting with profiles​

# Single profile
docker compose -f .github/docker-compose.yml --profile mail up -d

# Multiple profiles
docker compose -f .github/docker-compose.yml --profile mail --profile ai up -d

# Everything (not recommended — very resource heavy)
docker compose -f .github/docker-compose.yml --profile mail --profile ai --profile commonground --profile integrations up -d

Available profiles​

ProfileServicesPurposeResources
(default)db, nextcloud, exapp-n8nCore dev environment~1 GB
demonextcloud-demoSelf-contained demo (installs from app store)~1 GB
mailgreenmailTest mail server (SMTP/IMAP)~512 MB
matomomatomo, matomo-dbSelf-hosted web analytics (campaign reports)~1 GB
aipresidio, tgi-llm, dolphin-vlm, openanonymiser, exapp-openwebuiAI/LLM services~40 GB + GPU
ollamaollamaStandalone LLM inference~16 GB + GPU
uitilburg-woo-uiPublic WOO document frontend~256 MB
exappsharp, redisAppAPI infrastructure~1 GB
commongroundkeycloak, redisCommon Ground identity (OIDC)~3 GB
solr / searchsolr, zookeeperSolr search engine~1 GB
elasticsearchelasticsearchElasticsearch backend~1 GB
standalonen8n, open-webuiStandalone versions (not ExApps)~1 GB
llm-managementopenllmLLM model management~16 GB + GPU
mariadbdb-mariadb, nextcloud-mariadbMariaDB compatibility testing~1 GB
openproject / integrationsopenprojectProject management~4 GB
xwiki / integrationsxwikiWiki platform~4 GB
eurooffice / integrationseuroofficeOffice documents, PDF and PDF/A conversion~4 GB
ox / integrationsopen-xchangeEmail and groupware (requires registry access)~4 GB
exapps-legacydocker-socket-proxyLegacy AppAPI deploy daemon~128 MB

Service Details​

Core: Nextcloud + PostgreSQL​

ServiceContainerPortNotes
PostgreSQLconduction-postgres5432pgvector enabled, shared by all services
Nextcloudnextcloud8080Admin: admin / admin
n8n ExAppconduction-exapp-n8n—Via Nextcloud AppAPI proxy

All Conduction apps are mounted as volumes into Nextcloud's custom_apps directory. Changes to app source code are immediately reflected.

Mail & Groupware​

Two options are available depending on your needs:

GreenMail (--profile mail)Open-Xchange (--profile ox)
Use forDay-to-day development, quick testingProduction-like integration, client demos
ComplexityZero config, works immediatelyMulti-service, requires registry access
MailSMTP + IMAP (auto-create accounts)Full IMAP/SMTP via Dovecot/Postfix
CalendarUse Nextcloud Calendar (CalDAV)Built-in calendar + CalDAV
ContactsUse Nextcloud Contacts (CardDAV)Built-in contacts + CardDAV
Web UIREST API at :8085Full webmail at :8087
Seed dataScripts includedCLI user/context creation

Lightweight test mail server. Accounts auto-created on first email. No configuration needed.

ServiceContainerPortProtocol
GreenMailconduction-greenmail3025SMTP
3143IMAP
3110POP3
8085Web UI / REST API

Setup:

# 1. Start
docker compose -f .github/docker-compose.yml --profile mail up -d

# 2. Seed test emails (creates accounts automatically)
bash .github/docker/mail/seed-mail.sh

# 3. Seed contacts and calendar events into Nextcloud
bash .github/docker/mail/seed-pim.sh

Configure Nextcloud Mail app:

  • Go to Nextcloud (http://localhost:8080) → Mail app → Settings
  • Add account:
    • IMAP: Host greenmail, Port 3143, Security None
    • SMTP: Host greenmail, Port 3025, Security None
    • User: behandelaar@test.local (or any seeded address)
    • Password: same as the email address

Test accounts (auto-created by seed script):

EmailRoleDescription
admin@test.localSystem adminAdministrative notifications
behandelaar@test.localCase handlerProcesses applications and cases
coordinator@test.localTeam coordinatorPlanning, oversight, IT liaison
burger@test.localCitizenSubmits applications and complaints
leverancier@test.localSupplier/vendorExternal IT partner

Seed data includes:

  • 12 emails: case applications, status updates, internal coordination, complaints, deadlines
  • 6 contacts: citizens, civil servants, VNG architect, supplier (CardDAV)
  • 5 calendar events: sprint review, welstandscommissie, IT overleg, deadlines, retrospective (CalDAV)

All seed data is interconnected around realistic Dutch municipal case management scenarios (omgevingsvergunning, kapvergunning, IT-migratie).

Option B: Open-Xchange (for production-like testing)​

Full groupware suite with integrated webmail, calendar, contacts, and document editing (OX Text + Spreadsheet). Uses GreenMail as its IMAP/SMTP backend — the same mail server, so both OX and Nextcloud Mail see the same emails.

ServiceContainerPortPurpose
Open-Xchangeconduction-open-xchange8087Web UI (AppSuite)
OX MariaDBconduction-ox-mariadb—Dedicated database for OX
GreenMailconduction-greenmail3025/3143/8085Shared IMAP/SMTP (auto-starts)

Architecture:

GreenMail (IMAP/SMTP)
├── OX AppSuite → authenticates + reads/sends mail via IMAP/SMTP
└── Nextcloud Mail → reads/sends mail via IMAP/SMTP
Both see the same mailboxes and emails.

Setup:

# 1. Start OX (also starts GreenMail + OX MariaDB automatically)
docker compose -f .github/docker-compose.yml --profile ox up -d

# 2. Wait for OX to finish initialization (first boot takes 2-3 minutes)
docker logs -f conduction-open-xchange
# Wait for: "*** Restart completed ***"

# 3. Seed test emails into GreenMail
bash .github/docker/mail/seed-mail.sh

# 4. Create OX users and seed contacts/calendar
bash .github/docker/mail/seed-ox.sh

# 5. Access OX at http://localhost:8087/appsuite

Login credentials:

UsernamePasswordRole
oxadminoxadminContext admin
behandelaarbehandelaar@test.localCase handler
coordinatorcoordinator@test.localTeam coordinator
burgerburger@test.localCitizen
leverancierleverancier@test.localSupplier

Note: User passwords match their GreenMail email addresses because OX authenticates via IMAP against GreenMail.

What's included after seeding:

  • 5 user accounts with Dutch names and roles
  • 4 contacts (citizens, supplier, VNG architect)
  • 2 calendar appointments (welstandscommissie, IT-overleg)
  • 12 emails visible in OX webmail (from seed-mail.sh via GreenMail)
  • OX Text and Spreadsheet editors enabled

Connecting Nextcloud to OX:

  • Both OX and Nextcloud Mail share the same GreenMail IMAP server
  • Configure Nextcloud Mail with: IMAP host greenmail, port 3143 (same as standalone mail profile)
  • OX can mount Nextcloud files via WebDAV for document collaboration

Resource requirements:

  • OX needs ~2-4 GB RAM
  • First boot initializes databases and takes 2-3 minutes
  • Subsequent boots are faster (config is persisted in ox-etc volume)

AI Services (--profile ai)​

ServiceContainerPortPurpose
Presidioconduction-presidio-analyzer5001PII detection (Microsoft)
TGI LLMconduction-tgi-llm8081Text generation (HuggingFace)
Dolphin VLMconduction-dolphin-vlm8083Document parsing (Vision LM)
Anonymiqconduction-openanonymiser5002PII anonymisation
OpenWebUI ExAppconduction-exapp-openwebui—AI chat via Nextcloud

Requires NVIDIA GPU with Docker GPU support configured.

Common Ground (--profile commonground)​

Dutch government Common Ground services, running as Nextcloud ExApps:

ServiceContainerPortPurpose
Keycloakconduction-exapp-keycloak8180Identity management (OIDC)
Redisconduction-exapp-redis—Shared cache

Common Operations​

Reset the environment​

# Stop everything and remove volumes (full reset)
docker compose -f .github/docker-compose.yml down -v

# Restart
docker compose -f .github/docker-compose.yml up -d

Install apps after reset​

docker exec nextcloud php occ app:enable openregister
docker exec nextcloud php occ app:enable opencatalogi
docker exec nextcloud php occ app:enable softwarecatalog
docker exec nextcloud php occ app:enable nldesign
docker exec nextcloud php occ app:enable launchpad

Clear caches​

# OPcache (after PHP changes)
docker exec nextcloud apache2ctl graceful

# APCu
docker exec nextcloud php -r "apcu_clear_cache();"

# Brute force protection
docker exec nextcloud php occ security:bruteforce:reset 127.0.0.1

Fix file permissions​

docker exec -u root nextcloud chown -R www-data:www-data /var/www/html/custom_apps/

View logs​

# Nextcloud log
docker exec nextcloud tail -f /var/www/html/data/nextcloud.log

# Specific container
docker logs -f conduction-postgres

Port Map​

Quick reference for all service ports:

PortServiceProfile
2181ZooKeepersolr
2375Docker Socket Proxyexapps-legacy
3025GreenMail SMTPmail
3110GreenMail POP3mail
3143GreenMail IMAPmail
3306MariaDBmariadb
5001Presidio Analyzerai
5002Anonymiqai
5432PostgreSQL(default)
5678n8n (standalone)standalone
8080Nextcloud(default)
8081TGI LLMai
8083Dolphin VLMai
8085GreenMail Web UImail
8086OpenProjectopenproject
8087Open-Xchangeox
8088XWikixwiki
8089Matomomatomo
8090Euro-Officeeurooffice
8180Keycloakcommonground
8780HaRPexapps
8983Solrsolr
9200Elasticsearchelasticsearch
11434Ollamaollama

Euro-Office document server (--profile eurooffice)​

Runs the Euro-Office document server, the office back end of the eurooffice Nextcloud app ("Nextcloud Office"). It edits documents in the browser and converts DOCX, ODT, XLSX, PPTX, HTML and Markdown to PDF and PDF/A.

docker compose -p openregister -f .github/docker-compose.yml --profile eurooffice up -d --no-deps eurooffice
curl http://localhost:8090/healthcheck # true once it is ready, after about a minute

The server only accepts requests signed with its JWT secret. Set EUROOFFICE_JWT_SECRET (at least 32 characters) before starting it; the default is for local use only. Then install the eurooffice app and point it at the server:

occ app:enable eurooffice
occ config:app:set eurooffice DocumentServerUrl --value=http://localhost:8090/
occ config:app:set eurooffice DocumentServerInternalUrl --value=http://eurooffice/
occ config:app:set eurooffice StorageUrl --value=http://nextcloud/
occ config:app:set eurooffice jwt_secret --sensitive --value="$EUROOFFICE_JWT_SECRET"
occ eurooffice:documentserver --check

DocumentServerUrl is the address your browser uses; DocumentServerInternalUrl and StorageUrl are the addresses the two containers use to reach each other on conduction-network.

Matomo analytics (--profile matomo)​

Matomo is the fleet's self-hosted web analytics. The pipelinq marketing connectors read campaign, referrer and goal reports from it over the Reporting API, and portaliq traffic analytics can forward to it, so campaign attribution is developed without sending visitors to a third party.

docker compose -f .github/docker-compose.yml --profile matomo up -d

First run:

  1. Open http://localhost:8089 and walk through the install wizard. The database step is prefilled from the container environment (host matomo-db, database matomo, user matomo, password matomo).
  2. Create the first website for http://localhost:8080 (the Nextcloud dev instance). Its site id is 1.
  3. Create an auth token under Administration → Personal → Security. Paste it into the pipelinq Search and analytics settings as the Matomo token; pipelinq stores it as a credentialRef through the OpenRegister broker, never as a plain setting.

Campaign parameters follow Matomo's mtm_* names and the utm_* synonyms. Both are recognised without configuration.

Demo Mode (--profile demo)​

Self-contained demo environment that installs apps from the Nextcloud app store. No source code needed — just start and demo.

docker compose -f .github/docker-compose.yml --profile demo up -d

This starts a Nextcloud instance that automatically installs OpenRegister, OpenCatalogi, and Stackiq from the app store. Useful for demos, stakeholder reviews, and quick testing without a full development setup.

Note: The demo profile uses a different Nextcloud service than the default. Do not combine demo with the default profile.

Database Testing (--profile mariadb)​

The MariaDB profile provides compatibility testing against MariaDB instead of PostgreSQL.

# Start with MariaDB
docker compose -f .github/docker-compose.yml --profile mariadb up -d

An automated test script is available for running integration tests against both databases:

bash .github/docker/test-database-compatibility.sh

Key differences between PostgreSQL and MariaDB:

  • Vector search: Only available with PostgreSQL (pgvector)
  • Full-text search: Both supported, different syntax
  • JSON operations: PostgreSQL has richer JSON support
  • Boolean handling: MariaDB uses 0/1, PostgreSQL uses true/false

See docker/README-DATABASE-TESTING.md for detailed documentation.

Migrating from OpenRegister docker-compose​

If you were previously using openregister/docker-compose.yml, update your commands:

# Old
docker compose -f openregister/docker-compose.yml up -d

# New
docker compose -f .github/docker-compose.yml up -d

Container names have changed from openregister-* to conduction-* (except nextcloud which stays the same). The network is now conduction-network instead of openregister-network.

Note: You may need to remove old volumes if switching:

docker compose -f openregister/docker-compose.yml down -v
docker compose -f .github/docker-compose.yml up -d