Installation & Deployment

These services must be installed, running, and reachable from this host before the Provision Portal stack starts. None of them are deployed by this guide.

The MySQL minimum comes from application.yml (mysql.dialect: org.hibernate.dialect.MySQL8Dialect); the bundled drivers are com.mysql:mysql-connector-j:9.2.0 and com.oracle.database.jdbc:ojdbc11:23.6.0.24.10 (build.gradle). The ACS and Flowable schemas may live on the same database instance or on different ones — they are configured through independent JDBC URLs (application-mysql.yml / application-oracle.yml).

Network access to the hub.friendly-tech.com Docker registry (or offline image archives — see Offline Servers).

Access to FT_DISK — ProvAPI for the backend’s deployment files (compose.yml, the .env templates, the XML configuration package), and to FT_DISK — provision-portal for the UI’s TLS certificate.

Provision Portal uses the Flowable workflow engine for business process management. A dedicated database schema and user are required before first startup.

Neither service declares a custom networks: entry, so Compose puts both containers on its default project network and they reach each other by service name (provision-api, provision-portal).

provision-api declares extra_hosts: - "host.docker.internal:host-gateway". If the database or Northbound API runs on the host machine rather than in Docker, use host.docker.internal as the hostname — it resolves on Docker Desktop out of the box and, thanks to that extra_hosts entry, on Linux as well. The host’s real IP address works too. localhost / 127.0.0.1 will not work: inside the container they point at the container itself.

When the target host cannot reach hub.friendly-tech.com, pull both images on a machine that does have registry access, export them to an archive, transfer it, and load it on the offline host.

The connected machine can run Linux, macOS, or Windows — commands are given for both shells below. It does not need to be the same platform as the offline host.

Confirm both images are present before starting, so a missing or mis-architected image fails here rather than mid-startup:

Upgrades use the same flow: pull the new tags on the connected machine, transfer and load the archive, then docker compose up -d.

compose.yml mounts persistent data under ${DATA_FOLDER}; the shipped .env template defaults DATA_FOLDER to /usr/local. Set it to /usr/local/ft-system so this stack sits under the same root as every other Friendly Tech service instead of scattering directories directly under /usr/local/. Create the directories, and keep compose.yml and .env at that root:

The stack uses a two-layer environment file architecture. There is no separate file per database vendor — both containers read the shared root .env first, then their own per-service .env:

Both files are listed in env_file: in compose.yml, root first so the per-service file wins on a conflict:

The three files come from FT_DISK together with compose.yml (they are also in docker/ in the source repository). Put the shared one at the stack root and the per-service ones next to each service’s directory, then edit the values:

If the bundle you received contains only compose.yml and the root .env, write the two per-service files yourself — every variable below marked Required must be present, or the container exits at startup with Could not resolve placeholder …​ (see Troubleshooting):

Then fill in the root .env — database hosts, credentials, NORTHBOUND_API_URL, DATA_FOLDER=/usr/local/ft-system, TZ and JWT_SECRET — using the table below.

MySQL is the default; on MySQL no vendor-specific change is needed beyond replacing the passwords. Selecting Oracle is not a file swap — it is a set of variables changed inside the same root .env (SPRING_PROFILES_ACTIVE, the database host, port, service name and credentials). See Switching to Oracle for the full variable list, and Flowable Database Setup for the Oracle schema setup.

CMMN job polling is already off in application.yml (flowable.cmmn.async-executor-activate: false), so no environment override is needed for it.

Provision Portal UI (Nginx) — the primary, already-wired path. compose.yml mounts ${DATA_FOLDER}/provision-portal/ssl:/etc/nginx/ssl:ro; place a certificate and key there (friendly.crt, friendly.key per the FT_DISK bundle, or your own CA-issued pair under matching names expected by the UI’s Nginx config).

Provision API — serves HTTPS on 8443 from a self-signed keystore bundled inside the jar (classpath:keystore.p12, password friendly, key alias myapp, all set in application.yml). This is not overridden by anything in the shipped compose/env files and is suitable for testing only. To use a custom certificate, extend compose.yml yourself: mount a PKCS12 keystore and add the matching Spring Boot overrides under provision-api.environment:

server.ssl.key-alias is fixed to myapp in application.yml, so a replacement keystore created with any other alias (keytool -alias server …​, as the sibling FT guides use) is loaded but no matching key entry is found and the TLS connector fails to start. Either override SERVER_SSL_KEY_ALIAS with the alias your keystore actually uses, or generate the keystore with -alias myapp and drop that line.

Remember also to publish port 8443 (see the warning in Network Requirements) if this certificate needs to be reachable from outside the container.

provision-api has no depends_on on its infrastructure — the ACS database, the Flowable database, and Northbound API live outside this stack, so Compose cannot gate on their health. All of them must be reachable before provision-api starts: Liquibase applies the Flowable schema migrations on first start, and the JDBC pools connect during context initialisation.

provision-portal (the UI), by contrast, does depend on provision-api within this stack — depends_on: provision-api: condition: service_healthy — so it will not start until the backend’s healthcheck passes.

Wait for the external dependencies explicitly before starting:

The backend’s healthcheck has start_period: 60s, so provision-api legitimately reports starting for up to a minute before turning healthy; provision-portal stays down until it does.

/prov-portal/actuator/health reports both datasources (management.endpoint.health.show-details: always), so a database problem shows up there before it shows up in the UI:

Reachability from inside the backend container, and the values actually applied:

On first start, the Flowable tables are created by Liquibase; confirm they exist in the Flowable schema afterwards (ACT_RU_EXECUTION, ACT_RE_PROCDEF, and the rest of the ACT_* set).

All backend paths are under the servlet context path /prov-portal (application.yml).

Application log files are also written to the host through the bind mounts: provision-api/logs/ (→ /app/Log, set by LOGGING_CUSTOM_BASE_PATH / LOGGING_CUSTOM_DIRECTORY) and provision-portal/nginx/logs/ (→ /var/log/nginx).

provision-portal declares stop_grace_period: 45s, so a down or restart of the UI may take up to 45 seconds before the container is killed.

Liquibase migrates the Flowable schema automatically on the first start of a new version.

Symptom: provision-api or provision-portal exits immediately after docker compose up.

Fix:

Symptom: PlaceholderResolutionException: Could not resolve placeholder 'XML_PATH'

Fix:

Symptom: Application logs show a FileNotFoundException for the provisioning XML files.

Fix:

Symptom: MySQL Communications link failure or Oracle ORA-12514 in the logs.

Fix:

Symptom: Unknown database 'flowable' or ORA-01017: invalid username/password for the Flowable user in the logs.

Fix:

Symptom: Connection refused or timeout errors when calling Northbound API.

Fix:

Symptom: The UI loads but shows connection or authentication errors; provision-portal never becomes healthy despite provision-api being healthy.

Fix:

Symptom: address already in use error on docker compose up.

Fix:

[[401-or-403-from-the-ui-api-calls]] === 401 or 403 from the UI API Calls

Symptom: UI login succeeds, subsequent calls return 401/403, or tokens issued before a restart stop working.

Cause: JWT_SECRET was set (or changed) and the container restarted — all previously issued tokens are invalidated because they were signed with the old key.

Fix: re-authenticate through the UI. If this happens on every restart even without changing JWT_SECRET, confirm the variable is actually set in the root .env — otherwise the application falls back to its hardcoded default, which does not change between restarts but is also not a real fix; see Production Checklist.

When raising an issue, attach the output of the following so the deployment state is unambiguous:

Redact passwords before sharing. Include the image tags in use (docker compose images) and the contents of version.xml if you built the image yourself.