Installation & Deployment

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

Registry reachability is not a runtime dependency of this container and is therefore not listed above; it is covered by Registry Access and Registry Authentication.

The backend in turn reaches the Friendly TR-069 ACS and its database. Those are never contacted by the browser or by this container.

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

Read-only pull credentials for the registry are issued by the DevOps team; request them before starting. They are sufficient for installation and upgrades.

Access to FT_DISK — Provision Portal UI for compose.yml and the self-signed TLS pair; the shared root .env comes from the FT System MySQL Stack / FT System Oracle Stack folder, or is written from the three values in Environment Configuration. docker/docker-compose.yml in this repository is a local build-and-run file, not the deployment descriptor.

provision-portal joins the ft-network bridge of the ft-system Compose project, together with every other FT service on the host. It reaches the backend by whatever hostname FT_PROV_API_URL contains, resolved from inside the container — the provision-api service name on this host, an IP address across hosts; see Pointing at the Backend.

localhost and 127.0.0.1 never work here — inside the container they point at the container itself.

When the Provision Portal UI host cannot reach hub.friendly-tech.com, pull the image on a machine that does have registry access, export it 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 the image is present before starting, so a missing or mis-architected image fails here rather than mid-startup:

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

The platform layout gives each service one directory directly under /usr/local/ft-system, beside the host-level compose.yml and the shared .env. This container needs two directories of its own — an empty log directory does not survive a download:

This follows the platform layout documented in Full System Deployment: one directory per service directly under /usr/local/ft-system.

Every value this container needs comes from the shared root .env, which compose.yml uses twice: it hands the file to the container through env_file:, and it reads the same file to interpolate $\{…​} inside compose.yml.

This container needs no database, no Flowable schema, no Northbound API and no JWT secret: tokens are issued and validated by the backend.

There is no HTTPS_ENABLED switch and no keystore environment variable. nginx.conf.template contains listen 443 ssl unconditionally and reads /etc/nginx/ssl/friendly.crt and /etc/nginx/ssl/friendly.key, so in practice the certificate mount is mandatory: without it Nginx fails to start. TLSv1.2 and TLSv1.3 with ECDHE ciphers are configured in the template.

FT_DISK ships a self-signed pair, enough to start the container. To generate a fresh one on the deployment host (run from /usr/local/ft-system/provision-portal) — a deployment host installing from the registry image has no source checkout, so docker/generate-cert.sh is not available there, and the command below is what that script does:

In a source checkout the equivalent is cd docker && ./generate-cert.sh, which writes docker/ssl/friendly.crt and docker/ssl/friendly.key for the local build compose file.

For production, install a CA-issued pair under the same file names:

The certificate directory is mounted read-only at /etc/nginx/ssl and the HTTPS port is published by the stack compose.yml (${PROV_PORTAL_HTTPS_PORT:-8893}:443) — see Docker Compose.

Rotate certificates before expiry — the self-signed command above issues a 10-year certificate and is for internal use only. The container also serves plain HTTP on container port 80 (published as 8890); redirect or firewall it if your environment requires HTTPS only.

If Nginx fails to start because of the certificate, see Container Fails to Start.

provision-portal has no depends_on in the shipped compose.yml — the backend is external to that stack. Three conditions are on you:

There is no per-service env_file: layer for this container: everything it reads is in the root .env (Environment Configuration). Set FT_PROV_API_URL there before the first start (Pointing at the Backend); to change a published port, set PROV_PORTAL_HTTP_PORT / PROV_PORTAL_HTTPS_PORT in the same file.

docker/ops/entrypoint.sh prints, in order:

A WARN: nginx.conf.template not found or WARN: …​ app.config.json not found (skipping) line means the image is not the expected one.

Then open http://<HOST>:8890/provision-portal/ in a browser.

The published ports are the ones the platform assigns to this image; docker/docker-compose.yml in this repository publishes 8880:80 for local development only, and 8880 / 8843 belong to the Portals container on a shared host.

Online hosts:

Offline hosts: pull, save and transfer the new image as described in Offline Servers, then

To roll back, set the previous tag in compose.yml and run docker compose up -d provision-portal again.

Symptom: the container starts and immediately exits, or the log shows an SSL certificate error or an Nginx host not found in upstream error.

Cause and fix:

Symptom: the login page appears, but login fails or no data loads.

Check:

Fix:

Symptom: address already in use when starting the container.

Check: lsof -i :8890 or docker ps.

Fix: stop the conflicting process, or change PROV_PORTAL_HTTP_PORT in the root .env — see [env-file-is-not-interpolated] for why the published ports live there.

Symptom: the page loads blank, or the browser console shows errors.

Check: open DevTools → Console, and confirm assets/config/app.config.json is served and contains "apiUrl": "/prov-api/".

Fix: an empty or missing config file means the entrypoint’s jq patch did not run — check docker compose logs provision-portal for the Patched app.config.json line.

[[404-on-deep-links-or-refresh]] === 404 on Deep Links or Refresh

Symptom: opening a route directly, or refreshing, returns 404.

Fix: the location /provision-portal/ block uses try_files $uri $uri/ /provision-portal/index.html. Confirm the request path is under /provision-portal/ and that the build output was copied to /usr/share/nginx/html/provision-portal (docker compose exec provision-portal ls /usr/share/nginx/html/provision-portal). The CI build sets --base-href /provision-portal/; a build without it will not resolve its assets.

Symptom: the container starts but provision-portal/nginx/logs/ stays empty, or the log shows Nginx failing to open its log files.

Fix:

The ssl/ mount is read-only, so it needs read access only — but the key must stay unreadable to other users on the host.

Collect the following before contacting the Friendly Technologies support team:

Include the image tag in use and whether the host is online or offline.