Gateway Environment Variables

Almost every environment variable the gateway reads flows through a single module — src/application/settings.py — which evaluates ~80 os.getenv() calls at import time, coerces types, and applies defaults. Routes, services, and the rosbridge layer all import these module-level constants, so the exact names, defaults, and coercion in settings.py are load-bearing: renaming or re-typing one is a breaking change across the whole codebase. A handful of variables bypass settings.py and are read directly with os.getenv() elsewhere (email, APP_ENVIRONMENT, AWS credentials), and a few values that look configurable are actually hardcoded. This page enumerates everything, groups it by concern, and calls out every place a default disagrees between settings.py, .env.example, and the exported production ECS task definition.

Deeper mechanics live on sibling pages — this page is the reference table. See Startup, Validation & Composition Root for boot ordering and the fail-fast guards, VPN IP Authentication & Jumphost Routing for the network-trust model, OpenTelemetry & SigNoz for the OTEL wiring, and Migrations, DB Connection & Dev Mode for the database URI and APP_ENVIRONMENT.

Where configuration comes from

settings.py raises RuntimeError at import time if JWT_SECRET_KEY is empty on any non-local deployment (src/application/settings.py:299) — this fires before validate_critical_config() runs, so anything that imports settings triggers it. Set DEPLOYMENT_ENVIRONMENT=local to fall back to an insecure test key, or provide a real key.

Default mismatches — read before deploying

settings.py defaults are what runs when a variable is unset. The .env.example template and the production ECS task definition (docs/aws_prod_env_vars.env) both override several of them, so the code default is frequently not what runs in production. Do not assume the settings.py value.

Variable	`settings.py` default	`.env.example`	Production (ECS)
`DEPLOYMENT_ENVIRONMENT`	`server`	`local`	`server`
`USER_SITL_MAX_COUNT`	`3`	`5`	`5`
`SITL_CPU_LIMIT`	`2.0`	`2.0`	`1.0`
`SITL_VIDEO_STREAM_DRONE_STATE`	`ARMED`	`CONNECTED`	`CONNECTED`
`SEND_QUEUE_SIZE`	`30`	(unset → 30)	`200`
`LOG_LEVEL`	`20` (INFO)	`20`	`10` (DEBUG)
`REMOTE_DOCKER_HOST`	`ssh://nexus0@<office-docker-host>`	`ssh://nexus0@<office-docker-host>`	`tcp://jumphost-private.skyhub-prod.internal:2375`
`OTEL_EXPORTER_OTLP_ENDPOINT`	unset (OTEL off)	`http://<office-docker-host>:4318/v1/traces`	`http://jumphost-private.skyhub-prod.internal:4317`
`RESOURCE_TAG`	`skyhub-dev`	(unset)	`skyhub-prod`
`ACCOUNT_ID`	`123`	(unset)	`<aws-account-id>`

OTLP endpoint footgun. docker-compose.yml defaults the base endpoint to http://<office-docker-host>:4318, and the exporters append /v1/traces and /v1/logs themselves. But .env.example bakes the signal path into the base var (.../v1/traces), which would make the log exporter POST to /v1/traces/v1/logs. Production points at port 4317 (the gRPC port) while the code uses the HTTP exporter. Keep this a bare host:4318 base URL. See OpenTelemetry & SigNoz.

Deployment & environment

Variable	Default	Purpose
`DEPLOYMENT_ENVIRONMENT`	`server`	Master switch. `local` derives `IS_LOCAL_ENVIRONMENT=true`, enabling permissive CORS, the insecure JWT fallback, local `X-Drone-IP` whitelisting, and optional `VPN_BUCKET`. Any other value = strict/non-local.
`IS_LOCAL_ENVIRONMENT`	derived	Not a raw env var — computed as `DEPLOYMENT_ENVIRONMENT == "local"` (`settings.py:15`). Gates CORS, the JWT secret fallback, the `VPN_BUCKET` requirement, and middleware IP whitelisting.
`APP_ENVIRONMENT`	`production`	Not in `settings.py` — read directly in `main.py:265` and only in the `__main__` block. If `dev`, runs `db.create_all()` instead of Flask-Migrate. Distinct from `DEPLOYMENT_ENVIRONMENT`.
`ENABLE_SITL`	`true`	Gates lazy `SITLDroneService` init (`app.py:104`) and allows `SKYHUB_SITL_*` names via `X-Drone-IP` in the VPN middleware.
`ENABLE_REGISTRATION`	`true`	Toggles public user registration (`auth_routes.py:185,248`).
`ADMINS_ONLY`	`false`	Dead config — defined in `settings.py:9` but referenced nowhere else in `src`.
`FLASK_APP`	`main.py`	Flask CLI entrypoint for `flask db migrate` / `upgrade`. Read by the Flask CLI, not `settings.py`.
`SOCKET_IP`	`None`	Bind host for `socketio.run()` in the `__main__` dev path (`.env.example`: `0.0.0.0`). Ignored under gunicorn.
`LOG_LEVEL`	`20` (INFO)	Numeric root logger level (`configure_logging`); also the level of the OTEL `LoggingHandler`. Prod ships `10` (DEBUG).

Database

The URI is assembled in DBConnector as postgresql://{DB_USERNAME}:{DB_PASSWORD}@{DB_IP}/{DB_NAME} (src/connector/db_connection.py:29). All four values are .strip()ped in settings.py.

Variable	Default	Purpose
`DB_USERNAME`	`""`	PostgreSQL user.
`DB_PASSWORD`	`""`	PostgreSQL password.
`DB_IP`	`""`	PostgreSQL host. Critical — `validate_critical_config()` raises if empty. Prod: `database.skyhub-prod.internal`.
`DB_NAME`	`""`	PostgreSQL database name (prod: `skyhub`).

Authentication & JWT

Variable	Default	Purpose
`JWT_SECRET_KEY`	`test-secret-key-for-development-only` (local only)	HS256 signing key for access/refresh JWTs and the Socket.IO handshake. Required on non-local deployments — raises `RuntimeError` at import if empty (`settings.py:299`).

JWT_ACCESS_TOKEN_EXPIRES (10 min) and JWT_REFRESH_TOKEN_EXPIRES (12 h) are hardcoded timedeltas in main.py:247-248, not env-configurable — despite older docs listing them as env vars. The JWT algorithm is fixed to HS256, and the revocation BLOCKLIST is an in-memory set (does not survive restart or scale across workers).

VPN & jumphost routing

Variable	Default	Purpose
`VPN_SERVICE_IP`	`None`	Host of the external WireGuard status service queried by `VPN_Service` status endpoints.
`VPN_SERVICE_PORT`	`5050`	Port of the external VPN status service.
`VPN_BUCKET`	`None`	S3 bucket holding per-user/per-drone WireGuard `access.conf`. Critical only on non-local deployments (validated). Prod: `skyhub-prod-user-vpn`.
`JUMPHOST_IP`	`""`	If set, rosbridge `Connection`s route through `ws://JUMPHOST_IP:JUMPHOST_PORT` and add `x-drone-ip` / `x-drone-port` headers for Nginx multiplexing. Empty string → direct connection (`connection.py:27`, `self.direct = not self.jumphost_ip`).
`JUMPHOST_PORT`	`9090`	Port on the jumphost that fronts rosbridge.
`USER_NETWORK_CIDR`	`10.70.0.0/16`	WireGuard user subnet; `IPService` allocates user IPs here.
`DRONE_NETWORK_CIDR`	`10.71.0.0/16`	WireGuard drone subnet. The middleware trusts any source whose IP starts with `10.71.` and `IPService` allocates drone IPs here.

Jumphost mode is selected purely by whether JUMPHOST_IP is a non-empty string. Both the WebSocket Connection and its HTTP _test_connection() reachability probe must send identical x-drone-ip / x-drone-port headers, or the probe and the socket can diverge. Details in VPN Middleware & Jumphost.

SITL orchestration

SITL container lifecycle is documented in SITL Drone Lifecycle. Note the env-var-name → settings.py-constant remaps flagged inline below.

Variable	Default	Purpose
`SITL_IMAGE_NAME`	`ardupilot`	Docker image for SITL (ArduPilot) containers. Prod uses a full ECR image path.
`USER_SITL_MAX_COUNT`	`3`	Max SITL drones per user. Templates use 5.
`SITL_CPU_LIMIT`	`2.0`	CPUs per SITL container (prod `1.0`).
`SITL_MEMORY_LIMIT`	`4g`	Memory per SITL container.
`SITL_HOME_LOCATION`	`42.1403890,24.7645490,0,0`	Default spawn point as ArduPilot’s `--home "lat,lon,alt,heading"`. Overridable per request.
`SITL_DISABLE_VIDEO`	`false`	If `true`, simulated vehicles do not encode video (one `gst-launch` per armed aircraft costs ~⅓ core). Overridable per request.
`SITL_SIM_SPEEDUP`	`1.0`	`SIM_SPEEDUP` applied at creation. The achievable ceiling drops with fleet size — measure `sim_time_s` against wall clock before trusting a value.
`APP_IMAGE_NAME`	`skyhub-app:latest`	The merged core+agent image. `SKYHUB_ROLE` selects which half a container runs.
`CORE_IMAGE_NAME`	→ `APP_IMAGE_NAME`	Per-half override for the SITL `core` container (MAVROS + rosbridge). Exists so a deployment can pin one half to an older image without a code change.
`CORE_CPU_LIMIT`	`2.0`	CPUs per core container.
`CORE_MEMORY_LIMIT`	`2g`	Memory per core container.
`GAMEPAD_IMAGE_NAME`	→ `APP_IMAGE_NAME`	Per-half override for the agent container. Same image as `CORE_IMAGE_NAME` by default.
`GAMEPAD_CPU_LIMIT`	`0.5`	CPUs per gamepad container.
`GAMEPAD_MEMORY_LIMIT`	`512m`	Memory per gamepad container.
`GAMEPAD_API_URL`	`http://localhost:5000`	Backend URL the gamepad container calls for execution tracking.
`SITL_REDIS_IMAGE`	`redis:7-alpine`	Redis image for the shared SITL container group.
`SITL_REDIS_HOST`	`host.docker.internal`	Redis host for SITL/gamepad containers.
`REDIS_PASSWORD`	`skyhub_redis_secret`	→ `settings.SITL_REDIS_PASSWORD`. Redis auth for SITL containers.
`SITL_VIDEO_STREAM_DRONE_STATE`	`ARMED`	→ `settings.VIDEO_STREAM_DRONE_STATE`. Drone state at which SITL video streaming starts. Templates/prod use `CONNECTED`.
`LOG_ERASE_AFTER_DOWNLOAD`	`false`	If `true`, erase logs from the flight controller after a successful S3 upload.
`SITL_HOST`	`<office-docker-host>`	Derived from `DOCKER_HOST_IP` (`settings.py:252`). IP used to order/represent SITL drones in `IPService`.
`SITL_VPC_IP_PREFIX`	`172.31.`	VPC CIDR prefix trusted as a drone identity for Fargate SITL tasks, which call the gateway over the VPC rather than WireGuard. Empty string disables.
`SITL_EC2_ENABLED`	`false`	Run SITL containers on a managed EC2 instance instead of the office server.
`SITL_EC2_INSTANCE_ID`	`""`	Instance to start/stop for EC2 mode.
`SITL_EC2_REGION`	`REGION` or `eu-central-1`	Region of the SITL EC2 instance.
`SITL_EC2_AUTO_STOP`	`true`	Stop the instance when the last SITL container is deleted.
`SITL_EC2_DOCKER_PORT`	`2375`	Docker API port on the SITL EC2 instance.

SITL default ArduPilot parameters (fence + battery)

Applied to each new SITL drone at creation time. The battery values model the aircraft the simulated fleet stands in for — a T-Drones M690 Pro on a 6S 27 Ah pack.

Variable	Default	Purpose
`SITL_FENCE_ENABLE`	`1`	`FENCE_ENABLE` (1 = geofence on).
`SITL_FENCE_TYPE`	`7`	`FENCE_TYPE` bitmask (1=alt, 2=circle, 4=polygon → 7 = alt+circle+polygon).
`SITL_FENCE_ACTION`	`1`	`FENCE_ACTION` (1 = RTL on breach).
`SITL_FENCE_ALT_MAX`	`100`	Max fence altitude (m).
`SITL_FENCE_RADIUS`	`10000`	Circle fence radius (m). The old 300 m default put the corners of a 1 km survey box outside the fence and ArduPilot refused AUTO.
`SITL_BATT_VOLTAGE`	`25.2`	Simulated fully-charged 6S voltage (4.20 V/cell).
`SITL_BATT_CAPACITY`	`27000`	Battery capacity (mAh).
`SITL_BATT_EMPTY_VOLT`	`19.8`	Empty at 3.3 V/cell on 6S.
`SITL_BATT_HOVER_AMPS`	`74.0`	Draw coefficient, not amps at hover: current = idle + this × normalised throttle². Re-measure after changing airframe mass or `WPNAV_SPEED`.
`SITL_BATT_IDLE_AMPS`	`1.5`	Avionics draw with the motors stopped.
`SITL_BATT_LOW_VOLT`	`0`	Low-voltage failsafe disabled (0 = off in ArduPilot).
`SITL_BATT_CRT_VOLT`	`0`	Critical-voltage failsafe disabled.
`SITL_BATT_ARM_VOLT`	`0`	Arming voltage check disabled.
`SITL_BATT_FS_LOW_ACT`	`2`	Low-battery failsafe action (2 = RTL).
`SITL_BATT_FS_CRT_ACT`	`3`	Critical-battery failsafe action (3 = LAND).

The three voltage failsafes are off deliberately: they fired off a different number than the supervisors reason with, so the autopilot RTL’d an aircraft the relay still considered to have margin. The charge-remaining thresholds (SITL_BATT_LOW_PCT 25, SITL_BATT_CRT_PCT 12) drive BATT_LOW_MAH / BATT_CRT_MAH instead.

Docker host

Variable	Default	Purpose
`DOCKER_HOST`	`None`	Docker daemon socket/host string (`settings.py:196`).
`DOCKER_HOST_IP`	`None`	IP that SITL containers connect back to; SITL drones use this instead of `drone.ip`, and it also seeds `SITL_HOST`. Prod/template: `<office-docker-host>`.
`REMOTE_DOCKER_ENABLED`	`false`	If `true`, provision SITL containers on a remote Docker host rather than the local daemon. Prod: `true`.
`REMOTE_DOCKER_HOST`	`ssh://nexus0@<office-docker-host>`	Remote Docker connection string (`ssh://` or `tcp://`). Prod uses `tcp://jumphost-private.skyhub-prod.internal:2375`.

Video streaming

Video-room mechanics live in Janus Video Rooms. (SITL_VIDEO_STREAM_DRONE_STATE is listed under SITL above.)

Variable	Default	Purpose
`JANUS_URL`	`None`	Janus Gateway REST base URL for WebRTC video-room management. Prod: `http://janus.skyhub-prod.internal:8088/janus`.
`WHIP_SERVER_URL`	`None`	WHIP server base URL for video ingest. Prod: `http://whip.skyhub-prod.internal:7080`.

Socket.IO

Streaming behavior is documented in Socket.IO Telemetry Streaming.

Variable	Default	Purpose
`SOCKETIO_PING_TIMEOUT`	`60`	Flask-SocketIO ping timeout (s).
`SOCKETIO_PING_INTERVAL`	`25`	Flask-SocketIO ping interval (s).
`SOCKETIO_MESSAGE_QUEUE`	`None`	Optional Redis URL for multi-worker Socket.IO fan-out / horizontal scaling.
`DO_UNSUBSCRIBE`	`true`	If `true`, `unsubscribe_telemetry` actually stops the underlying rosbridge topic subscription (`socket_routes`).

Rosbridge & connection

Connection/reconnect internals live in Rosbridge Connection & Reconnect.

Variable	Default	Purpose
`MAX_RECONNECT_ATTEMPTS`	`15`	`SmartSocket` max reconnect attempts before `is_expired` (`socket.py:21`).
`MAX_RECONNECT_TIME`	`60`	Max seconds disconnected before `SmartSocket` gives up (`socket.py:22`).
`DRONE_REACHABILITY_TIMEOUT`	`2`	Connect/read timeout (s) for the HTTP reachability probe before opening a rosbridge socket.
`ROSBRIDGE_SERVICE_TIMEOUT`	`30.0`	Timeout (s) for rosbridge service calls (mission upload, geofence, param) — raised to 30 for WireGuard latency.
`REQUEUE`	`false`	If `true`, failed outgoing rosbridge messages are re-queued instead of dropped.
`SEND_QUEUE_SIZE`	`30`	Max size of the per-connection outgoing rosbridge message queue. Prod: `200`.
`TELEMETRY_THROTTLE_RATE`	`200`	Min interval (ms) between telemetry messages via rosbridge `throttle_rate`; `0` disables throttling.

Observability (OpenTelemetry / SigNoz)

Variable	Default	Purpose
`OTEL_EXPORTER_OTLP_ENDPOINT`	`None`	Gate. If unset, OpenTelemetry init is skipped entirely (`main.py:98`). Base OTLP-HTTP endpoint; exporters append `/v1/traces` and `/v1/logs`.
`OTEL_EXPORTER_OTLP_HEADERS`	`None`	Comma-separated `key=value` headers (e.g. `signoz-access-token=<redacted>`) attached to both span and log exporters.
`OTEL_SERVICE_NAME`	`skyhub_gateway_service`	`service.name` resource attribute in traces/logs.
`OTEL_RESOURCE_ATTRIBUTES`	`deployment.environment={DEPLOYMENT_ENVIRONMENT}`	Defined but never applied — `main.py` builds `Resource(attributes={...})` with hardcoded keys and does not read this var, so any extra attributes set here are silently dropped.

Billing (Stripe)

Billing logic lives in Stripe Billing & Vehicle Limits.

Variable	Default	Purpose
`STRIPE_SECRET_KEY`	`""`	Server-side Stripe API key. Redact (`sk_live_xxx` / `sk_test_xxx`).
`STRIPE_PUBLISHABLE_KEY`	`""`	Client-side Stripe key (`pk_xxx`).
`STRIPE_WEBHOOK_SECRET`	`""`	Webhook signature secret (`whsec_xxx`).
`STRIPE_PRICE_ID`	`""`	Price ID for the subscription product (EUR 120/vehicle/year).
`STRIPE_SUCCESS_URL`	`https://skyhub.ai/billing/success`	Checkout success redirect.
`STRIPE_CANCEL_URL`	`https://skyhub.ai/billing/cancel`	Checkout cancel redirect.

Email (SMTP)

All four MAIL_* values are read directly with os.getenv() in src/service/email_service.py:13-16 — they are not surfaced in settings.py, so they are easy to miss when auditing config.

Variable	Default	Purpose
`MAIL_SERVER`	`smtp.gmail.com`	SMTP host.
`MAIL_PORT`	`587`	SMTP port.
`MAIL_USERNAME`	`noreply@idrobots.com`	SMTP sender address.
`MAIL_PASSWORD`	`None`	SMTP app password. Redact.
`TEST_EMAIL_SERVER`	`true`	In `settings.py`. If `true`, `EmailService` runs a one-off SMTP login test at startup and warns (but continues) on failure; it does not disable real sending.

AWS & S3

REGION is the value settings.py exposes and is validated at startup; boto3 clients additionally pick up the standard AWS_* credential vars from the environment implicitly (they are never read in code).

Variable	Default	Purpose
`REGION`	`eu-central-1`	AWS region. Critical — validated at startup. Used for S3/asset ops.
`RESOURCE_TAG`	`skyhub-dev`	AWS resource-tag prefix used for installer/resource naming in `drone_routes`. Prod: `skyhub-prod`.
`ACCOUNT_ID`	`123`	AWS account id used in installer/ECR references. Prod: `<aws-account-id>`.
`ASSET_BUCKET`	`skyhub-prod-assets`	S3 bucket for assets (video/image/logs).
`INSTALLER_BUCKET`	`skyhubcore`	S3 bucket for drone installer artifacts (`drone_routes`).
`ECR_REPO`	`<aws-account-id>.dkr.ecr.eu-central-1.amazonaws.com`	→ `settings.DOCKER_REPO`. ECR registry for the SITL and application images.
`AWS_ACCESS_KEY_ID`	`None`	boto3 credential (implicit; not read in `settings.py`). Redact.
`AWS_SECRET_ACCESS_KEY`	`None`	boto3 credential (implicit). Redact.
`AWS_DEFAULT_REGION`	`eu-central-1`	boto3 region auto-detect. The lazy `get_vpn_service()` exists to ensure `REGION` is set before the S3 client is built (`app.py:70`).

Variables that are hardcoded, not env-driven

Some behavior that operators expect to configure via env is fixed in code. Changing it requires a code change, not a variable:

Behavior	Where it lives	Value
Access-token TTL	`main.py:247`	`timedelta(minutes=10)`
Refresh-token TTL	`main.py:248`	`timedelta(hours=12)`
JWT algorithm	`main.py:246`	`HS256`
CORS / Socket.IO origins	`main.py:188-193,210`	`localhost:4200`, `dev.skyhub.ai` (local); `skyhub.ai`, `api.skyhub.ai` (prod)
HTTP/Socket.IO listen port	`main.py:270`	`5000`

Adding a new frontend origin is a code change (main.py), not an env var. The two environment switches — DEPLOYMENT_ENVIRONMENT (local/server) and APP_ENVIRONMENT (dev/production) — are independent and easy to confuse: the first drives CORS/JWT/middleware behavior, the second only gates db.create_all() in the python main.py dev path.

Minimal local `.env`

The shipped .env.example boots a fully local dev stack (SITL enabled, insecure defaults). The smallest set that gets the gateway running against a local Postgres:

.env

DEPLOYMENT_ENVIRONMENT=local
JWT_SECRET_KEY=<redacted>            # optional locally; falls back to a test key
DB_USERNAME=idrobots
DB_PASSWORD=idrobots
DB_IP=skyhub-postgres
DB_NAME=skyhub
REGION=eu-central-1
SOCKET_IP=0.0.0.0
ENABLE_SITL=true

For production parity, cross-reference Production Configuration and the platform-wide Environment Variables reference.

Startup, Validation & Composition Root

How these variables are validated and consumed during boot — fail-fast guards, init order, and dev-mode schema creation.

HTTP & Socket.IO API

Services & Realtime Internals

Data, Config & Ops

Gateway Environment Variables

Where configuration comes from

Default mismatches — read before deploying

Deployment & environment

Database

Authentication & JWT

VPN & jumphost routing

SITL orchestration

Docker host

Video streaming

Socket.IO

Rosbridge & connection

Observability (OpenTelemetry / SigNoz)

Billing (Stripe)

Email (SMTP)

AWS & S3

Variables that are hardcoded, not env-driven

Minimal local `.env`

Startup, Validation & Composition Root

​Where configuration comes from

​Default mismatches — read before deploying

​Deployment & environment

​Database

​Authentication & JWT

​VPN & jumphost routing

​SITL orchestration

​Docker host

​Video streaming

​Socket.IO

​Rosbridge & connection

​Observability (OpenTelemetry / SigNoz)

​Billing (Stripe)

​Email (SMTP)

​AWS & S3

​Variables that are hardcoded, not env-driven

​Minimal local .env

Startup, Validation & Composition Root

Where configuration comes from

Default mismatches — read before deploying

Deployment & environment

Database

Authentication & JWT

VPN & jumphost routing

SITL orchestration

Docker host

Video streaming

Socket.IO

Rosbridge & connection

Observability (OpenTelemetry / SigNoz)

Billing (Stripe)

Email (SMTP)

AWS & S3

Variables that are hardcoded, not env-driven

Minimal local `.env`