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)