Configuration
Environment variables, make targets, and the built-in limits of the server and dashboard.
Server (apps/server)
The server reads these variables from the environment — every CLI flag falls back to its
variable, so a container needs no argument list. make run exports apps/server/.env and
passes explicit flags, which still win over the environment.
| Variable | Default | Notes |
|---|---|---|
MACHINE_ID | — (required) | Unique machine ID (16-bit number, must not be 0) |
APP_SECRET | — (required) | Signs JWTs and derives the credential encryption key; a new install refuses fewer than 32 characters |
PORT | 8080 | Port for the gateway + dashboard API |
ENV | development | development enables dev behavior (sample key seeding); the release image and Compose examples set production via the container env |
DEBUG | false | true/1 enables debug mode |
DATABASE_PATH | terarouter.db | SQLite file location |
MIGRATE_ON_BOOT | false | Run migrations on start; Compose examples pass true |
SEED_ON_BOOT | false | Seed initial data (roles, admin, Default plan); Compose examples pass true |
ADMIN_EMAIL | admin@tera.local | Admin email; a change renames the existing admin on the next seed |
ADMIN_PASSWORD | admin123 (dev) | Admin password — required in production; a change is synced to the admin on the next seed |
ADMIN_TOTP_RESET | — | Set to true to turn off the admin's two-factor auth on the next seed; unset it after signing in |
CORS_ALLOWED_ORIGINS | * (dev), empty (prod) | Comma-separated origin list, e.g. http://localhost:5173,http://localhost:3001; empty means same-origin only |
TRUSTED_PROXIES | — | Comma-separated proxy IPs/CIDRs trusted to supply X-Forwarded-For |
RATE_LIMIT_EXEMPT_IPS | — | Comma-separated client IPs that bypass the dashboard rate limit |
RESTRICTED_ACCESS_DISABLED | false | Set to true to ignore the Restricted Access period without changing it, e.g. after locking yourself out; unset it once you are back in |
API_URL | — (same origin) | Public API base URL injected into the served dashboard and written into agent skill guides; set it for a split origin or behind a proxy |
APP_NAME | tera-router-server | Application name |
SENTRY_DSN | — | Enables error tracking when set |
OIDC_ISSUER | — | OIDC issuer base URL (Pocket ID, Keycloak, …); enables dashboard SSO when all three are set |
OIDC_CLIENT_ID | — | OIDC client ID |
OIDC_CLIENT_SECRET | — | OIDC client secret |
OIDC_PROVIDER_NAME | SSO | Provider display name on the login button ("Continue with Pocket ID") |
OIDC_REDIRECT_URL | derived | Callback URL registered at the provider ({public URL}/v1/auth/oidc/callback); set it when a proxy hides the public scheme or host |
OIDC_REQUIRE_EMAIL_VERIFIED | true | Refuse sign-ins whose email_verified claim is false or absent |
OIDC_DISABLE_PASSWORD_LOGIN | false | Hide and refuse password and passkey sign-in so SSO is the only way in; applies only while OIDC is enabled |
OIDC_LINK_EXISTING_ACCOUNTS | true | Let an OIDC sign-in link itself to an existing account with the same email; off means only provisioned or already-linked accounts use SSO |
OIDC_AUTO_PROVISION | true | Create a user account for an OIDC sign-in whose verified email matches none; off means an admin must create the account first |
OIDC_ALLOWED_DOMAINS | (empty) | Comma-separated email domains allowed to sign in via SSO; empty allows all. Applies to every SSO sign-in, linked accounts included |
HEADROOM_URL | http://localhost:8787 | Default Headroom proxy for Settings → Token Saving; a URL saved in the dashboard overrides it |
HEADROOM_PROXY_TOKEN | — | Bearer token sent to a Headroom proxy bound beyond loopback (e.g. a compose sidecar) |
APP_SECRET is the house key
Provider credentials are encrypted with a key derived from APP_SECRET. Changing the secret makes
every stored credential unreadable. Change it only before data exists, and keep it safe. Generate
it with openssl rand -hex 32: a new install does not start with a secret shorter than 32
characters, and an existing one logs a warning.
Make targets (apps/server)
| Target | Notes |
|---|---|
make run | Run the API server (reads .env) |
make install | Set up the Go toolchain |
make migrate/up | Run migrations |
make migrate/down | Roll back migrations |
make migrate/refresh | Reset the database |
make seed | Seed production data |
make seed/dev | Seed the "Dev" sample key (plaintext printed once) |
make test | Tests |
make vet | Static analysis |
make build/api | Build the server binary |
Dashboard (apps/web-ui)
| Variable | Default | Notes |
|---|---|---|
API_URL | http://localhost:8080 | API server address (dev only — in production the server's API_URL env wins) |
VITE_APP_NAME | Tera Router | Display name |
The dashboard runs on port 5173 (pnpm dev in apps/web-ui).
Built-in limits
| Limit | Value |
|---|---|
| Maximum request body size | 32 MiB |
| Server read timeout | 20 seconds |
| Server write timeout | 3 minutes |
| Unary request deadline | 90 seconds |
| Stream deadline | 3 minutes |
| SSE heartbeat | 15 seconds |
| Gateway concurrency (in-flight) | 100 |
| Dashboard rate limit | 100 req/min per IP (/assets/ exempt) |
| Key verification cache | 5 minutes |
| Retries per request (max) | 10 |
| Account cooldown (429 / auth fail) | 30 seconds / 5 minutes |