Local Stack — Guide

Version 1.6.9-option-3 | Updated: August 07, 2026

Local Stack — Guide

Local development environment for the FTACS platform. Spins up the full stack of 20+ services with a single command, then deploys monitoring (Prometheus, Grafana, Alertmanager) with exporters and 16 pre-configured dashboards.

Table of Contents

Full Setup (Start to Finish)

Prerequisites

  • Linux server with Docker and Docker Compose v2.20+

  • At least 16 GB RAM (32 GB recommended for with-ai group)

  • At least 10 GB free disk space

  • qa-shared repository cloned (e.g., at /opt/qa-shared)

  • grafana-github repository cloned (e.g., at /opt/grafana)

Step 1 — Start the FTACS Platform

cd /opt/grafana/local-stack
bash local-stack.sh

The setup wizard will walk you through:

  1. Database selection — MySQL (default, faster) or Oracle

  2. Service group — minimal / api / full / with-ai / custom

  3. Port check — auto-resolves conflicts

  4. Container startup — pulls images, starts services, waits for health checks

After completion you will see:

Local Stack is running
─────────────────────────────────────────────
QA Platform (mysql)
MySQL ····································· 65.109.58.165:3307  (ftacs / ftacs  db=ftacs)
FTACS ····································· http://65.109.58.165:8080/FTACS/  (friendly / linux4israel)
...
Dashboard:  http://65.109.58.165:8888/dashboard.html  (admin / <password>)

Verify: open http://<IP>:8080/FTACS/ in browser — FTACS login page should appear.

Step 2 — Deploy Exporters (Metrics Collectors)

cd /opt/grafana
REPO_BRANCH=local-stack bash misc/bootstrap.sh <IP> auto

Replace <IP> with your server’s IP address.

This auto-detects running services and deploys the appropriate exporters:

  • node-exporter (9100) — server hardware metrics

  • process-exporter (9256) — process metrics

  • cAdvisor (9183) — container metrics

  • mysqld-exporter (9104) — MySQL metrics

  • clickhouse-exporter (9116) — ClickHouse metrics

  • postgres-exporter (9187) — PostgreSQL metrics

  • nginx-exporter (9113) — Nginx metrics

  • jmx-exporter-hikari (5556) — HikariCP connection pool metrics

The FTACS javaagent (port 5557) provides JVM metrics natively — no standalone exporter needed.

Expected result: 17 OK, 0 failed, 0 warnings

Step 3 — Deploy Monitoring Stack (Prometheus + Grafana)

cd /opt/grafana
REPO_BRANCH=local-stack bash misc/bootstrap.sh <IP> stack

This deploys:

  • Prometheus — metrics collection and alerting engine

  • Grafana — dashboards and visualization (16 pre-configured dashboards)

  • Alertmanager — alert routing and notifications

  • Nginx — reverse proxy with HTTPS

  • Mailpit — email testing (captures alert emails)

  • SNMP Notifier — SNMP trap forwarding

  • SNMP Catcher — SNMP trap receiver with web UI

After completion, Grafana is available at: https://<IP>/ (credentials shown in output).

Step 4 — Verify Everything Works

cd /opt/grafana
bash misc/diagnose.sh

Expected output:

  • All containers running (✓)

  • All ports listening (✓)

  • All metrics endpoints responding (✓)

  • 19/19 Prometheus targets UP

Or run the full automated test suite:

bash misc/testing/test-bootstrap.sh --verify-only

Expected: 147 passed, 0 failed

Step 5 — Open Dashboards

Open Grafana at https://<IP>/ and explore:

  • System Dashboard — CPU, memory, disk, network for the server

  • Nodes Monitoring — detailed node metrics (115 panels)

  • MySQL — queries, connections, InnoDB, replication

  • FT UI Services — container status, ClickHouse, PostgreSQL, Nginx, APIs

  • JMX Dashboard — JVM heap, GC, threads for FTACS

  • Hazelcast Overview — cluster state, maps, queues, memory

  • Hikari — database connection pool health

  • Alerts Monitoring — alert status by category (Platform, Connectivity, Resources, Business)

  • Alerts Combined Overview — firing/pending alerts, notification history

All dashboards auto-select the first available instance — no manual configuration needed.

Commands

  • bash local-stack.sh — interactive menu (or first-run wizard)

  • bash local-stack.sh up — start (if already configured: offers start/modify/clean)

  • bash local-stack.sh down — stop all QA services

  • bash local-stack.sh restart — full restart (down + up)

  • bash local-stack.sh reload — restart only stopped/failed containers

  • bash local-stack.sh status — container status table

  • bash local-stack.sh dashboard — regenerate dashboard and show URL

  • bash local-stack.sh logs — FTACS logs (tail -f)

  • bash local-stack.sh logs <service> — specific service logs (e.g. logs northbound-api)

  • bash local-stack.sh monitoring — monitoring setup instructions

  • bash local-stack.sh clean — remove all data, configs, volumes

  • bash local-stack.sh help — command reference

Flags

  • --debug or DEBUG=1 — verbose output, full command logging

  • --clean — reset saved config, re-run wizard

  • --qa-dir=/path — manually specify qa-shared repo path

Service Groups

minimal — Minimal FTACS Environment

Services: MySQL, Hazelcast, ClickHouse, JDBC Bridge, FTACS, Configs Service, Configs UI, System Metrics RAM usage: ~8 GB

api — FTACS + Public APIs (no UI)

Everything from minimal + Northbound API, Service API, Provision API RAM usage: ~9 GB

full — Full Stack with UI

Everything from api + Portals, UI Backend, Provision Portal, Device Network Service, QoE Web, TR-069 Emulator, IoT Emulator RAM usage: ~12 GB

with-ai — Full Stack + AI Agent

Everything from full + AI Agent, PostgreSQL RAM usage: ~14 GB

custom — Manual Selection

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).

Services and Ports

Databases

  • MySQL — port 3307 (user: ftacs / ftacs, DB: ftacs)

  • Oracle — port 1522 (user: ftacs / ftacs, DB: ftacs)

  • PostgreSQL — port 5432 (user: postgres / postgres, DB: ftl_ai) — AI Agent only

  • ClickHouse — port 8123 (user: ftacs / ftacs, DB: ftacs)

Infrastructure

  • Hazelcast — port 5701 (in-memory cache/clustering)

  • JDBC Bridge — port 9000 (ClickHouse JDBC bridge)

  • Keycloak — port 8500 (SSO/authentication, user: admin / admin)

Core

  • FTACS — port 8080, path /FTACS/ (user: friendly / linux4israel)

    • HTTPS: 8443

    • MQTT: 1883, MQTT TLS: 8883

    • USP WebSocket: 8025, USP MQTT: 18881, USP STOMP: 61617

    • JMX: 9999 (for HikariCP monitoring)

    • Prometheus javaagent: 5557 (JVM metrics)

APIs

  • Northbound API — port 8082, health: /iot-webservice/actuator/health

  • Service API — port 8083, health: /iot-webservice/actuator/health

  • Provision API — port 8084, health: /prov-portal/actuator/health

UI

  • Portals — port 8880 (management web UI)

  • UI Backend — port 8881 (Angular API Backend), actuator on 9881

  • Provision Portal — port 8890, path /provision-portal/

  • Device Network — port 8383 (Network Discovery Service)

  • Configs Service — port 8086, health: /configs-service/actuator/health

  • Configs UI — port 3001

AI and Monitoring

  • AI Agent — port 8184 (FastAPI, requires PostgreSQL)

  • System Metrics — port 8680 (HikariCP + business metrics)

  • QoE Web — port 8085

Emulators

  • TR-069 Emulator — CPE device emulator

  • IoT Emulator — port 8556, IoT device emulator

Dashboard

  • Dashboard — port 8888 (HTTP Basic Auth, password auto-generated)

Service Dependencies

Dependencies are resolved automatically. Selecting a service adds all its dependencies.

  • portals → ui-backend → ftacs → (mysql/oracle, hazelcast, clickhouse)

  • service-api → northbound-api → ftacs

  • provision-portal → provision-api → northbound-api → ftacs

  • ui-ai-agent → postgres + ui-backend + ft-device-network-service

  • ft-configs-ui → ft-configs-service

Port Conflicts

On startup, local-stack checks all ports automatically. If a port is occupied (e.g., monitoring-stack Prometheus on 9090), the script finds a free port:

⚠ Port conflicts detected (auto-resolved):
·   Prometheus: 9090→9091
·   Grafana: 3100→3101

Resolved conflicts are saved in the state file and reapplied on each startup.

Monitoring

Local-stack does NOT manage the monitoring stack (Prometheus, Grafana, Alertmanager). They are managed separately via bootstrap:

# Step 1 — Exporters (node-exporter, mysqld-exporter, etc.)
cd /opt/grafana && REPO_BRANCH=local-stack bash misc/bootstrap.sh <IP> auto

# Step 2 — Monitoring stack (Prometheus + Grafana)
cd /opt/grafana && REPO_BRANCH=local-stack bash misc/bootstrap.sh <IP> stack

JMX Metrics

FTACS and Hazelcast ship with built-in jmx_prometheus_javaagent:

  • FTACS JVM — port 5557 (jvm_info, jvm_memory, java_lang)

  • Hazelcast — port 9101 (com_hazelcast_*, jvm_info)

  • HikariCP — port 5556 (standalone jmx-exporter-hikari via JMX 9999)

Container Memory Limits

Limits are set in the auto-generated docker-compose.qa-network.yml:

  • FTACS: 4 GB

  • MySQL: 2 GB

  • Hazelcast: 2 GB

  • ClickHouse: 1.5 GB

  • Keycloak: 1.5 GB

  • UI Backend: 1.5 GB

  • Provision API: 1 GB

  • Northbound/Service API: 768 MB

  • Device Network: 768 MB

  • PostgreSQL, AI Agent, FT Configs Service: 1 GB

  • Portals, Provision Portal, Configs UI, System Metrics, JDBC Bridge: 512 MB

Java heap is auto-scaled based on available Docker memory.

Files and Directories

Generated files (not committed)

  • docker-compose.qa-network.yml — compose override (network, ports, limits, javaagent)

  • dashboard.html — generated HTML dashboard page

  • data/logs/ — session logs (local-stack-YYYYMMDD-HHMMSS.log)

  • ~/.local-stack/state — saved configuration (DB_TYPE, SERVICE_GROUP, etc.)

  • ~/.local-stack/dashboard-pass — dashboard password

Source files

  • local-stack.sh — entry point, command routing

  • lib/config.sh — service groups, dependencies, config generation

  • lib/compose.sh — Docker Compose orchestration, health-check waiting

  • lib/checks.sh — prerequisites, port management, firewall checks

  • lib/dashboard.sh — dashboard HTML generation and terminal summary

  • lib/ui.sh — colored output, spinners, interactive menus

  • service-registry.yaml — service metadata (ports, credentials, descriptions)

  • jmx-agent-config.yml — JMX Prometheus config (MBeans whitelist)

  • jmx_prometheus_javaagent.jar — JAR for JVM metrics

  • templates/dashboard.html — dashboard HTML template

Testing

bash tests/test-local-stack.sh

88+ tests across 30 sections: service groups, profiles, dependencies, config generation, dashboard, state persistence, cleanup.

Troubleshooting

Docker not running

✗ Docker daemon is not running

Fix: systemctl start docker

qa-shared not found

The script will prompt for the path. Make sure the qa-shared repository is cloned.

Port occupied

Automatically resolved. If that fails — stop the conflicting service or use clean to reset.

DockerHub timeout

⚠ Failed (attempt 1/3). Retrying in 5s...

3 automatic retries. If it persists — check internet or VPN.

Container stuck restarting

bash local-stack.sh logs <service>   # check logs
bash local-stack.sh restart          # full restart

Full reset

bash local-stack.sh clean           # remove data + configs
bash local-stack.sh                 # re-run wizard