Local Stack — Guide

local-stack deploys the FTACS platform itself — MySQL, FTACS, Hazelcast, the APIs and the UI — in containers, and then the monitoring is pointed at it. That makes it a self-contained test bed, and it also means it does not belong on a server that already runs FTACS: the ports it needs are exactly the ones the real platform occupies. On such a server deploy only the exporters (bootstrap.sh <prometheus-ip> auto).

--update means get the code and deploy nothing. On a clean host it clones, on an existing checkout it pulls. The repository is private, so this wrapper is the only way to fetch it — it carries the access token.

Two ways to run it. Interactively, if you want to see and choose everything:

The wizard asks four things, each with a description of what it means:

Or non-interactively, with the same choices as flags:

qa-shared is cloned automatically. On a clean host the first run takes roughly 10 minutes, nearly all of it pulling about 18 GB of images; once they are cached a start takes 2—​4 minutes on MySQL.

What each group actually starts. Measured on the test stand, 06.08.2026, all eight combinations with cached images, every container healthy:

The database does not change what starts: on the same group Oracle and MySQL give the same containers. It changes how long the first start takes — Oracle spends several minutes initialising before anything else can come up, which is most of the difference on minimal.

custom is not “only the services you name”. --services="ftacs northbound-api" started 12 containers: the database, Hazelcast, ClickHouse, the JDBC bridge and the rest of the infrastructure come along, because the named services do not run without them.

Replace the IP with the address of the Prometheus server (the same machine here).

--local-stack tells bootstrap that the platform it just detected is a stand: it reads the ports and credentials from the stand’s own configuration, provisions a dedicated exporter database user inside the container, and never touches the host’s native database. Without the flag it asks; under -y it takes the stand by default; --no-local-stack opts out.

The stack itself — Prometheus, Grafana, Alertmanager and the alert channels — is documented in the main installation guide; only what the stand needs is repeated here.

Asks for the Grafana and Prometheus passwords, SMTP and the alert channels. Add -y to take defaults: passwords are then generated and printed at the end.

A healthy environment reports 0 failed and looks like this:

Dashboards need a separate check — a target can be UP while the series a panel asks for does not exist, and the panel then reads “No data” with nothing reporting a problem:

It runs every panel’s own query and lists the empty ones. Some emptiness is correct and should not be chased:

A surprising result is more likely a bad query rewrite than a broken panel: open the dashboard in Grafana before acting on it. The variables are substituted textually here, and a matcher written with single quotes (tag0='$map') once turned into an exact match on the literal .*, reporting a dozen healthy panels as empty.

Comparing against a reference installation is what separates “this stand lacks the source” from “this panel is broken for everyone” — run the same script on the monitoring host that watches real servers and diff the two.

Then check Prometheus and Grafana:

Credentials are also in /opt/grafana/prometheus-grafana-stack/.env (GRAFANA_ADMIN_PASSWORD, PROMETHEUS_USER, PROMETHEUS_PASSWORD).

Same path, one flag:

Oracle is heavier — the database alone takes several minutes before anything else can start. Expect the same containers as on MySQL (19 for with-ai) and, with the monitoring deployed, 16 targets UP. Measured with cached images: minimal 6m46s against MySQL’s 3m37s, the gap being Oracle’s initialisation; once it is up the larger groups are no slower than MySQL.

Two things are specific to it:

To reset the machine completely, including images:

--host must name the machine you are on — its short name, its FQDN or one of its addresses. That is the point of it: the commands below are the same ones that reset a test stand and destroy a monitoring host, and nothing in them says which is which. Without --yes the script only prints the plan.

A native (non-Docker) database on the host is untouched. The script records which database ports are served by a non-container process before it starts and fails if one of them stops answering, so “the wipe took the host’s MySQL with it” cannot pass unnoticed.

What it runs, for reference:

plus the leftovers experiments accumulate (/root/hz-test, /root/podman-poc, /root/grafana-backup-*). Note that the first line fails on an already-clean machine — with no containers the substitution is empty and docker reports “requires at least 1 argument”; the script handles that.

They are consulted in this order — the first one that has an answer wins:

A component with no entry anywhere keeps whatever qa-shared specifies.

To check what a running stand actually pulled:

mysql (or oracle), hazelcast, clickhouse, jdbc-bridge, jstun, ftacs, ft-configs-service, ft-configs-ui, ft-system-metrics RAM usage: ~8 GB

Everything from minimal + northbound-api, service-api, provision-api, provision-portal RAM usage: ~9 GB

Everything from api + portals, ui-backend, ft-device-network, keycloak RAM usage: ~12 GB

Everything from full + ui-ai-agent, postgres RAM usage: ~14 GB

Interactive checklist: space to toggle, Enter to confirm. Core services (MySQL, Hazelcast, ClickHouse, FTACS) are locked — always included. Dependencies are resolved automatically (e.g., selecting Portals adds UI Backend).

FTACS and Hazelcast ship with built-in jmx_prometheus_javaagent:

The dashboards filter by instance. If one host is registered in servers.env under several names — say NODE as DB-MySQL while JMX_HC is still poc-hazelcast from an old experiment — the series under the odd name match nothing and those panels stay empty while every target is UP.

More than one name (ignoring the documented -grafana-proxy suffix) is the problem. Make the lines agree, then:

The deploy warns about this, and never rewrites the file itself — the inventory is yours to edit.

Deliberate. Monitoring finds these ports by number, so shifting one would give a stand that comes up, looks healthy and is never scraped. The message names the process holding the port. Free it — usually a real FTACS platform on the same host, another stand, or a leftover test container.

The one exception is 9101: if the monitoring stack’s own Hazelcast exporter holds it, the stand steps aside instead of refusing (see step 4 above).

compose aborts the entire up when a single service cannot be created — a missing image, a port already bound. Everything else is left in Created, which reads like a hang rather than a failure. Look above the summary for the actual compose error; one service explains all of them.

The exporters reach JMX over RMI, and RMI hands the client an address for the follow-up connection. The exporters run with host networking, so that address must be the host’s — a container name resolves only inside the compose network.

The reverse proxy is crash-looping. Its self-monitoring listener collides with something else on the host and nginx exits on the failed bind, taking the whole web surface with it.

The port is configurable (NGINX_STATUS_PORT in the stack’s .env) and the deploy moves it automatically when it is taken.

The qa-shared clone is incomplete — usually interrupted. Its .env.mysql and .env.oracle are tracked in the repository, so a healthy clone always has them. Re-fetch:

That is the wrapper, and it reads like a session-limit problem. Read the nested error — it is almost always:

A containerised Oracle XE lacks the full timezone region set, so a JDBC driver sending a region name (Europe/Kyiv) is refused. The stand passes -Doracle.jdbc.timezoneAsRegion=false to every FT service; if you see this again, check that the flag reached the container:

Check whether there is anything to report before suspecting the build. Business panels read from the platform’s own tables, and a fresh stand has none:

Zero rows means the panels are correct and simply have nothing to draw. The exporter’s own counters confirm it is querying: look for spring_data_repository_invocations_seconds_count with repository="CpeRepository".

systemctl start docker

Three automatic retries. If it persists, check connectivity to hub.friendly-tech.com. Note that the tags the stand uses are pinned in local-stack/image-tags.conf — a tag that no longer exists in the registry fails here, and the fix is to update that file, not to retry.