Installation & Deployment

The portals container is lightweight: static assets served by Nginx, no JVM and no local database. Size the host for the UI Backend and the infrastructure separately.

These services must be reachable from the container. None of them are deployed by this guide.

The UI Backend in turn needs its own database (MySQL or Oracle), Hazelcast, FTACS and — for QoE data — ClickHouse. The portals reach none of them directly. Those dependencies, their versions and their ports belong to the UI Backend deployment guide.

The published image is built for linux/amd64 — the default platforms input of .github/workflows/build-callable.yml. Another architecture requires a CI run with an explicit platforms value.

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

All upstream calls now originate in the container, so name resolution follows Docker’s rules:

The /ai-agent/ and /grafana-ro/ locations resolve their upstreams at request time: the entrypoint reads the first nameserver from /etc/resolv.conf and injects it as the Nginx resolver, which works in both Docker (127.0.0.11) and Kubernetes (CoreDNS). A restart is therefore not needed when those upstream IP addresses change.

When the portals 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 only image for this deployment is hub.friendly-tech.com/ui/portals:<tag>.

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 -f compose.portals.yaml up -d portals. See Stack Management.

The portals need a TLS certificate directory and, optionally, a log directory on the host. They use the common installation root /usr/local/ft-system (DATA_FOLDER), with this service’s files under portals/ — the Compose file mounts portals/ssl and portals/nginx/logs from there.

Every volume in compose.portals.yaml is written as ${DATA_FOLDER:-.}/…​. Compose resolves a relative path against the directory that holds the Compose file, so with DATA_FOLDER unset the mounts still land under /usr/local/ft-system as long as compose.portals.yaml sits there. To pin the path independently of where the Compose file lives, keep DATA_FOLDER=/usr/local/ft-system in the root .env next to it — Compose reads that file for variable interpolation. Setting DATA_FOLDER in the shell is not required, and relying on it is fragile: the value is lost in the next login shell.

The platform uses a two-layer environment file architecture, and the portals follow it. The portals hold no database configuration at all.

Use the exact file sources and destination paths in Download Deployment Files.

Root .env — values Compose interpolates before the container starts and values shared with other services:

Keep the other variables in the downloaded shared .env; the complete file intentionally contains values that portals do not use. Do not repeat any of the variables above in portals/.env: that file is loaded after the root .env, so a copy there overrides the shared value, and Compose never reads it when it substitutes the published ports.

portals/.env — values read only by docker/ops/entrypoint.sh and Nginx:

To brand the portals for a specific customer, create the branding directory next to the other portals/ host paths and populate it with any of the four supported files:

Mount it read-only at the path named by FT_BRANDING_DIR (default /branding) — see Branding (Optional). The full file list, the per-file fallback behavior and the operator warnings live in Configuration — Branding; this section covers only where the folder lives on the host.

Ready-made asset sets for existing customers are already checked in and can be copied as a starting point:

docker/ops/nginx.conf declares listen 443 ssl unconditionally and reads the certificate from fixed paths:

Those files are not baked into the image — they come from the mounted portals/ssl directory. Nginx refuses to start when either is missing, so the mount is required even when only HTTP is published. Protocols are restricted to TLS 1.2/1.3 with ECDHE-GCM ciphers.

For a self-signed certificate (development and internal installations), use the bundled generator. It writes ssl/friendly.crt and ssl/friendly.key relative to the current directory, valid for ten years, with SANs for friendly-tech.com, *.friendly-tech.com, localhost and 127.0.0.1:

For a CA-issued certificate, copy the PEM files under the expected names:

The entrypoint uploads permissions to the backend as soon as the container starts, using curl -f under set -euo pipefail. If the backend is unreachable or rejects the upload, the entrypoint exits and Nginx never starts. Wait for the backend before bringing the portals up:

With restart: unless-stopped the container retries on its own, so a backend that comes up shortly afterwards resolves the situation without intervention — the wait loop simply avoids the noisy restart cycle.

compose.portals.yaml is the dedicated Compose file from FT_DISK (see Download Deployment Files). Run it from /usr/local/ft-system with docker compose -f compose.portals.yaml. It joins the external ft-network, which has to exist before the first start (docker network create ft-network, once per host). The file as shipped:

What the entrypoint does. On start, docker/ops/entrypoint.sh performs five steps before Nginx serves traffic:

Branding is part of the ordinary compose file — there is no separate overlay to apply and no extra -f on the command line. Both settings are optional: leave them out and the container behaves exactly as before.

FT_COMPANY_NAME goes into portals/.env (see Environment Configuration):

The images come from portals/branding/ under DATA_FOLDER. compose.portals.yaml mounts it unconditionally, so there is nothing to switch on:

Drop in the files you want to override and recreate the container; leave the folder empty and the portals keep their built-in artwork without a word:

A WARN for an absent file appears only once at least one supported file is in the folder — that is, once branding is visibly in use and something was forgotten.

See Branding Folder (Optional) for creating portals/branding/ on the host, and Configuration — Branding for what goes in the folder, the per-file fallback behavior, and the operator warnings that apply regardless of which deployment method is used.

docker/ops/nginx.conf defines a single server block listening on 80 and 443:

Check the container reached a healthy state:

Expected:

Confirm the entrypoint rendered the configuration, patched the apps, applied branding and uploaded the permissions:

Expected lines: nginx.conf generated with FT_UI_BACKEND_URL=…​; two Patched …​ lines that differ by portal path (the script logs the full path, not the basename — both apps' configs share the basename app-config.json, so only the full path tells the lines apart):

+

+ one branding: file=<name> portal=<portal> applied line per branding file present in the folder, per portal — two lines per file, one for Support Portal and one for Management Portal. An installation that does not brand (an empty or absent folder — this guide’s baseline) produces no WARN at all, just one informational branding: dir=…​ using built-in defaults line. A WARN: branding: …​ line appears only once the folder holds at least one supported file and others are missing — one line per missing file. See Configuration — Branding; and Upload done (sc). / Upload done (mc).

Expected: HTTP 200 for the portals, 301 for the no-slash form.

Confirm the runtime config was patched:

Expected value:

If FT_COMPANY_NAME or FT_BRANDING_DIR are in use, confirm they landed. The Patched …​ startup log line already shows the company value (see Startup Log); check the served config directly, and use the branding: file=…​ applied log lines to confirm which images came from the mounted folder rather than the built-in defaults:

Expected: "company": "<the value you set>", and one branding: file=<name> portal=support-center applied / branding: file=<name> portal=management-console applied pair per file present in FT_BRANDING_DIR.

Finally, open both apps in a browser:

The portals listen on no other ports.

For offline servers, replace docker compose pull with the archive transfer flow in Offline Servers, then run docker compose -f compose.portals.yaml up -d portals.

Collect the following before contacting Friendly Tech support: