Skip to content

Mirrored from the simulator repository

This page is the simulator repository's own docs/DOCKER_NETWORK_AND_API.md, mirrored verbatim so it ships in the same documentation build as the other simulator guides. The simulator repository copy remains the source of truth.

BESS Simulator Frontend — Docker networking and API reference

This document lists every URL the BESS Simulator frontend uses or exposes, and how to reach each one over the Docker network.

Source of truth:

What Where
Frontend app root/bess-simulator-frontend -> /opt/gess-stack/bess-simulator/frontend/app
Compose file docker-compose.maria.yml (stack root, i.e. /opt/gess-stack)
Frontend config config/bess_simulator.php
Backend API EnergySyc_EMS_ES100Cx12S_BESS_simulator/register_api_server.py

1. Containers

All three simulator containers share the compose profile bess_simulator, so none of them start unless that profile is enabled.

Compose service Container name Image Profile Listens on
bess-simulator-nginx bess-simulator-nginx nginx:1.27-alpine bess_simulator 80
bess-simulator-frontend bess-simulator-frontend built from php:8.1-fpm bess_simulator 9000 (PHP-FPM)
bess-simulator-backend bess-simulator-backend built from python:3.10-slim bess_simulator 8000 (Register API), 1501-1641 (Modbus TCP; the running set depends on the deny list)
mariadb mariadb mariadb:10.11 database 3306
traefik traefik ${TRAEFIK_IMAGE} core 80, 443, 18880

Request path for a browser hit:

browser -> traefik:443 (or bess-simulator-nginx:9698)
        -> bess-simulator-nginx:80
        -> bess-simulator-frontend:9000   (FastCGI)
        -> bess-simulator-backend:8000    (HTTP, the Register API)

2. Docker networks

Three bridge networks are declared, so their real names are prefixed with the Compose project name:

Compose name Real name Members
web <project>_web traefik, all *-nginx/*-web services, both simulator containers
db <project>_db mariadb, timescaledb, and every app that needs a database
vpn <project>_vpn WireGuard-related services

The project name is the basename of the directory holding the compose file. On the deployed server the stack runs from /opt/gess-stack:

gess-stack_web      <- Docker service discovery happens here
gess-stack_db       <- mariadb is reachable here
gess-stack_vpn

maria-compose.service pins this:

WorkingDirectory=/opt/gess-stack
ExecStart=/usr/bin/docker compose -f docker-compose.maria.yml up -d

Which container sits on which network

bess-simulator-frontend, bess-simulator-backend and bess-simulator-nginx are each attached to both web and db.

mariadb is attached to db only. This is the single most common cause of "database unreachable" errors: a container that is only on web resolves other web services fine but has no route to mariadb. Anything that needs the database must join db.

Gotcha: the Traefik network label is hardcoded

bess-simulator-nginx carries:

- "traefik.docker.network=gess-stack_web"

This literal gess-stack_web is not derived from the project name. If the stack is started from a directory that is not named gess-stack, the networks become <other-dir>_web/<other-dir>_db and Traefik cannot find the container, so the public host stops routing. Run the stack from /opt/gess-stack, or edit that label to match.

Confirm the names on a live host

docker network ls | grep -E 'web|db'
docker inspect bess-simulator-nginx \
  --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'

3. API URLs

3.1 Frontend -> simulator backend (Register API)

Base URL, from config/bess_simulator.php:

'backend_url' => env('BESS_SIMULATOR_BACKEND_URL', 'http://bess-simulator-backend:8000'),
Setting Env var Default
Base URL BESS_SIMULATOR_BACKEND_URL http://bess-simulator-backend:8000
Bearer token BESS_SIMULATOR_API_TOKEN (empty — auth disabled)
Timeout BESS_SIMULATOR_API_TIMEOUT 10 seconds

The hostname bess-simulator-backend resolves because both containers are members of the same user-defined bridge network (web). Do not substitute localhost or 127.0.0.1 — inside a container those refer to the container itself, not the host and not its siblings.

Endpoints, served by register_api_server.py on port 8000:

Method Path Request Response
GET /health — {"status":"ok"}
GET /api/models — {"models":[...]}
GET /api/model — {"model":"<name>"}
POST /api/model {"model":"<name>"} {"model":"<name>"}
GET /api/devices ?model=<name> (optional) {"devices":[...]}
GET /api/scan — {"count":n,"devices":[...]}
GET /api/<device> — register document for that device
PATCH /api/<device> {"document": <object or array>} replaces the whole file; {"updates": [ ... ]} merges — note this one is a JSON list, not an object {"device":"<id>","updated":true} or "updated":<count>
GET /api/write-commands ?limit=200 {"commands":[...],"count":n}
DELETE /api/write-commands — {"cleared":true,"count":0}

<device> is a resource path that may contain slashes, for example pcs/pcs1 or grid. It maps to a file under emsConfig/.

Authentication: if the backend is started with REGISTER_API_TOKEN set, every request needs Authorization: Bearer <token>. The frontend sends this automatically when BESS_SIMULATOR_API_TOKEN is set — keep both values equal. POST /api/model additionally rejects bodies outside 1 byte – 1 MiB.

The two PATCH /api/<device> body shapes behave differently, so they are worth spelling out:

# Replace the entire register file with a new document (object or array).
curl -X PATCH http://bess-simulator-backend:8000/api/pcs/pcs1 \
  -H 'Content-Type: application/json' \
  -d '{"document": {"registers": []}}'          # -> {"device":"pcs/pcs1","updated":true}

# Merge a list of per-register updates into the existing file.
curl -X PATCH http://bess-simulator-backend:8000/api/pcs/pcs1 \
  -H 'Content-Type: application/json' \
  -d '{"updates": [{"name": "soc", "value": 55}]}'   # -> "updated": <count changed>

Sending {"updates": {"name": "soc"}} as an object fails with body must contain an updates array or a document.

3.2 Frontend -> EMS backend (settings and register map)

The frontend reads everything it knows about the EMS over HTTP. Neither file is copied into the shared volume any more:

Method Path Purpose
GET http://ems-backend:8080/api/v1/ems/settings ems_control_setting.json: the device table and each device's status
GET http://ems-backend:8080/api/v1/ems/register-map the merged ems_register_full.json the Modbus server loads

App\Support\EmsSimulator fetches the settings and joins them to the simulator's own /api/device-models inventory. The settings do not name register files, so the two are matched by group and unit position. The /ems/registers page fetches the map, flattens it to one row per register and caches the rows for EMS_REGISTER_CACHE_SECONDS; its Refresh register map from EMS button re-reads the endpoint and bypasses that cache.

Both endpoints are unauthenticated and reachable only on the Docker network - ems-backend publishes no port to the host.

3.3 Frontend routes (browser)

Served by nginx on port 80, reachable at http://localhost:9698 on the host or https://<BESS_SIMULATOR_HOST> through Traefik. Defined in routes/web.php:

Method Path Route name
GET / pcs.index
GET /dashboard pcs.dashboard
POST /dashboard/scan pcs.scan
POST /dashboard/model pcs.model.select
GET /devices/{device} pcs.show
POST /devices/{device}/update pcs.update
GET /monitor pcs.monitor
GET /monitor/data pcs.monitor.data
POST /monitor/clear pcs.monitor.clear

{device} again accepts slashes (->where('device', '.*')).

Note these are web routes. routes/api.php only contains the default Sanctum /api/user stub — the frontend is not itself a JSON API.

3.4 Modbus TCP endpoints (simulated devices)

bess-simulator-backend starts one Modbus TCP server per SCRIPTS entry in start_simulator.sh. Which of those actually run is decided by the deny list in emsConfig/device_enabled.json, written from the dashboard's Active Models page: every register path named there is skipped at startup, and everything not named runs. The port numbers are therefore not a contiguous block, and the set changes when devices are switched on or off — read the running set rather than assuming a range:

docker exec bess-simulator-backend ps -eo args | grep '[m]odbus_server'

Measured on the test host (25 servers running):

Port Device Register file
1501, 1502, 1509, 1510 pcs1, pcs2, pcs9, pcs10 emsConfig/pcs/pcs<N>/pcs_register_full.json
1513 grid_meter1 emsConfig/grid_energy_meter/grid_meter1/gridMeter_register_full.json
1514 solar_meter1 emsConfig/solar_energy_meter/solar_meter1/solarMeter_register_full.json
1520–1524 door_sensor1, flood_sensor1, smoke_sensor1, heat_sensor1, temperature_sensor1 emsConfig/<family>/<name>/…_register_full.json
1531 bess_energy_meter1 emsConfig/bess_energy_meter/bess_energy_meter1/bess_energy_meter_register_full.json
1532 ffrMeter1 emsConfig/ffr_energy_meter/ffrMeter1/ffrMeter_register_full.json
1630–1641 ev_charger1–ev_charger12 emsConfig/ev_charger/ev_charger<N>/ev_charger_register_full.json

Declared in SCRIPTS but switched off by the current deny list, so not reachable: pcs3–pcs8, pcs11, pcs12 (1503–1508, 1511, 1512), grid_meter2–grid_meter12 (1602+), solar_meter2–solar_meter12 (1603+), frequency_meter1 (1515), ac1–ac6 (1516+), cooling1 (1517), fss1 (1518), sensorB1 (1525), ups1 (1530) and bmu1–bmu10 (1543–1552). Three further SCRIPTS entries own no Modbus port at all and are never switched off: SOC dynamics, the Register API (8000) and the OCPP client.

Reach the running ones in-network as bess-simulator-backend:1501 etc. The ports are also published on the host for external tools, which is why an EMS backend can talk to either the simulator or real hardware by flipping one variable:

MODBUS_MODE: SIM
MODBUS_SIM_HOST: bess-simulator-backend
MODBUS_SIM_PORT_BASE: 1501
MODBUS_REAL_HOST: 192.168.50.10
MODBUS_REAL_PORT_BASE: 1516

So port 1501 reaches PCS1 when MODBUS_MODE=SIM, and the same logical device is expected at 192.168.50.10:1516 in real-hardware mode.

3.5 Database

Host:     mariadb          (network: db)
Port:     3306
Database: bess_simulator_db
User:     bess_simulator_user

There is no ports: mapping on mariadb — it is deliberately not exposed to the host. Reach it from inside a container, or via docker exec.


4. Reaching the APIs from each vantage point

From another container on the same network

docker exec ems-backend curl -s http://bess-simulator-backend:8000/health
docker exec ems-backend curl -s http://bess-simulator-backend:8000/api/models
docker exec bess-simulator-frontend curl -s http://bess-simulator-backend:8000/api/scan

With a token configured:

docker exec ems-backend curl -s -H "Authorization: Bearer $TOKEN" \
  http://bess-simulator-backend:8000/api/model

From inside the frontend container

Useful to verify the exact path the app takes:

docker exec -it bess-simulator-frontend sh
curl -s "$BESS_SIMULATOR_BACKEND_URL/health"
php artisan tinker --execute="echo config('bess_simulator.backend_url');"

From the host

curl -s http://localhost:9698/                 # nginx -> frontend
curl -s http://127.0.0.1:1501 -o /dev/null     # Modbus TCP, expect no HTTP reply

The Register API on 8000 is not published to the host, so from the host you have to route through a container or the nginx front door.

From outside the server

Traefik terminates TLS on 443 for the host derived from APP_URL:

- "traefik.http.routers.bess-simulator.rule=Host(`${BESS_SIMULATOR_HOST}`)"
- "traefik.http.routers.bess-simulator.entrypoints=websecure"
- "traefik.http.routers.bess-simulator.tls.certresolver=letsencrypt"
- "traefik.http.services.bess-simulator.loadbalancer.server.port=80"

APP_URL=https://bess-sim.gess-sweden.com in bess-simulator/frontend/app/.env is what gess-stack_build.sh reads to derive BESS_SIMULATOR_HOST, so the public URL and APP_URL must agree.


5. Shared write-command channel

This is not network traffic — it is a bind mount, and it is how an external controller pushes register writes into the simulator.

bess-simulator-backend   ./ems/shared -> /var/ems-shared
ems-backend              ./ems/shared -> /var/ems-shared
bess-simulator-frontend  ./ems/shared -> /var/ems-shared

GET /api/write-commands reads the queue that writers drop into that directory; DELETE /api/write-commands clears it. Because all three containers mount the same host path, no network route is involved and the permissions of the host directory matter more than DNS.


6. Environment variables

bess-simulator/frontend/app/.env (generated from bess-simulator.env):

Variable Value in this stack Purpose
APP_URL https://bess-sim.gess-sweden.com public URL; Traefik host derives from it
BESS_SIMULATOR_BACKEND_URL http://bess-simulator-backend:8000 Register API base URL
BESS_SIMULATOR_API_TOKEN (unset) bearer token, must match REGISTER_API_TOKEN
DB_HOST mariadb database host on the db network
DB_PORT 3306
DB_DATABASE bess_simulator_db
DB_USERNAME bess_simulator_user
DB_PASSWORD bess_simulator_password
EMS_SHARED_DIR /var/ems-shared shared write-command directory

The EMS variables are not set in this stack, so the defaults in config/bess_simulator.php apply:

Variable Default Purpose
EMS_SETTINGS_URL http://ems-backend:8080/api/v1/ems/settings EMS settings API
EMS_REGISTER_MAP_URL http://ems-backend:8080/api/v1/ems/register-map EMS merged register map
EMS_REGISTER_CACHE_SECONDS 60 how long the flattened map rows stay cached
EMS_CONFIG_TIMEOUT 60 HTTP timeout for both EMS calls

Backend-side (set in the compose service, not the frontend .env):

Variable Default Purpose
BIND_HOST 0.0.0.0 must stay 0.0.0.0 so the API is reachable from other containers
REGISTER_API_HOST falls back to BIND_HOST
REGISTER_API_PORT 8000
REGISTER_API_TOKEN (unset) enables bearer auth when set
SIM_ROOT /app/EnergySyc_EMS_ES100Cx12S_BESS_simulator
LOG_DIR <SIM_ROOT>/logs

7. Troubleshooting

bess-simulator-frontend returns 502 from nginx. nginx proxies FastCGI to bess-simulator-frontend:9000. The stock php:8.1-fpm image listens on 127.0.0.1:9000, which is unreachable from another container, so the Dockerfile rewrites it. If that sed line is removed:

RUN sed -i 's/^listen = 127.0.0.1:9000/listen = 9000/' /usr/local/etc/php-fpm.d/www.conf

Frontend cannot reach the database. Check that the container is on db:

docker inspect bess-simulator-frontend \
  --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'

Public URL 404s but :9698 works. Traefik cannot see the container. Verify the project name produces gess-stack_web, which is what the hardcoded traefik.docker.network label demands (section 2).

Backend calls time out. BESS_SIMULATOR_API_TIMEOUT defaults to 10 seconds. A /api/scan over a large emsConfig/ tree can exceed that; raise it rather than retrying.

401 on every backend call. BESS_SIMULATOR_API_TOKEN is set but does not match the backend's REGISTER_API_TOKEN, or vice versa. Setting only one side always fails.


8. Quick reference

Frontend (browser)     http://localhost:9698   or  https://bess-sim.gess-sweden.com
Frontend FastCGI       bess-simulator-frontend:9000
Register API           http://bess-simulator-backend:8000
Register API health    http://bess-simulator-backend:8000/health
Modbus PCS1..PCS12     bess-simulator-backend:1501..1512
Modbus grid meter      bess-simulator-backend:1513
Modbus solar meter     bess-simulator-backend:1514
Modbus freq meter      bess-simulator-backend:1515
Database               mariadb:3306  (bess_simulator_db)
Networks               gess-stack_web, gess-stack_db, gess-stack_vpn
Shared dir             /var/ems-shared  (host ./ems/shared)