Quick Start¶

Prerequisites¶

• Python 3.13 or newer (or Docker, see Docker).
• Network access to the inverter's TCP port 8899.
• The packaged protocol catalog (installed with the application).

Install¶

python -m pip install -e '.[dev]'

Without development tools, python -m pip install -e . installs the runtime dependencies only.

Configure¶

Copy settings.env.example to settings.env:

cp settings.env.example settings.env

The file only holds start parameters (HMAC_SECRET, BIND_ADDRESS, BIND_PORT, ALLOW_NON_LOOPBACK_BIND and optionally ADMIN_DB_PATH). Devices, authentication, API tokens, logging and export are configured in the administration GUI. For Docker, supply a stable random HMAC_SECRET (openssl rand -base64 32) before starting. Local startup generates the secret in settings.env if absent.

The application reads settings.env beside run.py automatically. --env-file selects another file. Environment variables take precedence. See Environment Variables for all settings.

Administration and tokens¶

Open http://127.0.0.1:8000/ after starting the server. The first start prints a boxed FIRST START - admin login block with the one-time admin password (8 characters, one special character) in clear text, so it can be copy-pasted straight from the console. It is also saved to initial-admin-password next to the admin database as a fallback for runs without a visible console:

cat data/initial-admin-password

The first login requires a new password (at least 8 characters) before other administration pages become accessible; delete the file afterwards.

Until that password is changed, the service is running but idle: the HTTP server and the administration GUI are reachable, while periodic reads, heartbeat polling, metric collection and the InfluxDB/QuestDB export stay stopped. The log shows Initial admin password not changed yet: ... paused ... as a warning. After the password change these jobs start automatically; no restart is needed. Later starts with an already changed password run normally.

Create a PAT on API tokens and copy it to your API client; its secret is shown only once. API authentication defaults to enabled even before a PAT exists. See Authentication.

Validate and start¶

python -m app validate     # configuration, object registry and write allowlist
python -m app              # start the server (serve is the default mode)

Check the service:

curl http://127.0.0.1:8000/health
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/api/v1/devices

Administration menu¶