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.

This repository does not ship a pre-configured deployment package. The compose.yml and the TLS certificate directory are created on the target host from the examples in this guide; docker/docker-compose.yml in this repository is a local build-and-run file, not the deployment descriptor.

The container reaches the backend by whatever hostname FT_PROV_API_URL contains, resolved from inside the container:

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.

Create the deployment directory on the host:

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

The platform uses a two-layer environment file architecture, and this service reads only the first layer:

There is no per-database-vendor env file. Selecting Oracle instead of the default MySQL means changing DB_PROFILE, SPRING_PROFILES_ACTIVE, DB_HOST and the other variables listed in Switching to Oracle inside the single root .env; compose.yml maps the generic DB_* names to the vendor-specific ones each application expects through the x-db-env / x-flowable-env YAML anchors. None of this reaches the Provision Portal UI container, which never talks to a database.

The variable read by this container:

The browser’s API base path is not configurable. docker/ops/entrypoint.sh rewrites assets/config/app.config.json with jq so that .apiUrl is the fixed relative value /prov-api/, matching the Nginx location. The browser calls /prov-api/…​ same-origin, Nginx forwards to FT_PROV_API_URL.

The Angular app loads assets/config/app.config.json before it boots (ConfigService.loadConfig() in an app initializer), so apiUrl is available to the first HTTP call. See Configuration.

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.

For local or internal use, generate a self-signed pair directly on the deployment host (run from /usr/local/ft-system, where the Directory Structure step left you). A deployment host installing from the registry image has no source checkout, so docker/generate-cert.sh is not available there; 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 compose.yml in Docker Compose (${PROV_PORTAL_HTTPS_PORT:-8893}:443).

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.

Create compose.yml in the deployment directory:

FT_PROV_API_URL is taken from the shared root .env. Do not add it under environment: in compose.yml — a compose environment: entry always wins over env_file, so it would pin one host for every deployment and, since Nginx resolves the proxy_pass host at startup (Startup Dependencies), the container would fail to start wherever that host does not resolve. Set the value once in .env:

To change a published port, set PROV_PORTAL_HTTP_PORT / PROV_PORTAL_HTTPS_PORT in .env, or edit only the left side of a mapping (<host>:<container>).

docker/docker-compose.yml in this repository is the local build variant: it builds from docker/Dockerfile, tags the result ui/provision-portal:tmp and publishes 8880:80 for local development only. The platform assigns this image the published ports 8890 → 80 and 8893 → 443 (Full System Deployment — Port Reference, PROV_PORTAL_HTTP_PORT / PROV_PORTAL_HTTPS_PORT in the environment reference); 8880 / 8843 on a shared host belong to the Portals container and would collide. This guide follows the platform — see docs/decisions/LOG.md.

Without Compose. The same deployment as a single docker run, executed from /usr/local/ft-system (where the Directory Structure step left you):

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 only the published side of the mapping (8080:80 instead of 8890:80).

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 bundle 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 bundle built without it will not resolve its assets.

Collect the following before contacting the Friendly Technologies support team:

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