306 lines
14 KiB
Markdown
306 lines
14 KiB
Markdown
# Environment Variables
|
|
|
|
Configuration reference for all Dotcom Arcade services.
|
|
|
|
## Backend Variables
|
|
|
|
Location: `backend/.env` (local development)
|
|
|
|
**Server:**
|
|
|
|
| Variable | Default | Description |
|
|
| ---------- | ----------- | ------------------------------------------ |
|
|
| `NODE_ENV` | development | Environment: development, production, test |
|
|
|
|
> **Note:** Port (3100) and bind address (0.0.0.0) are hardcoded in the backend.
|
|
> In Docker, use `API_PORT` to map a different host port to the container.
|
|
|
|
**Paths:**
|
|
|
|
| Variable | Default | Description |
|
|
| ---------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
| `FLASHPOINT_PATH` | `D:/Flashpoint` (dev), `/data/flashpoint` (prod) | Root Flashpoint directory. All other paths auto-derived. Edition (Infinity/Ultimate) auto-detected from `version.txt`. |
|
|
| `FLASHPOINT_GAMES_PATH`| `<FLASHPOINT_PATH>/Data/Games` | Override game ZIP directory (rarely needed). |
|
|
| `APP_VERSION` | set by the Docker build | Release version the server reports on Settings → Update. Baked into the official image from the release tag; set it by hand for a non-Docker deployment, or update checks stay off. |
|
|
|
|
**Authentication & Security:**
|
|
|
|
| Variable | Default | Description |
|
|
| -------------------- | --------------------- | ---------------------------------------------------- |
|
|
| `JWT_SECRET` | auto-generated (dev) | Secret for JWT signing (**required in production**) |
|
|
| `JWT_EXPIRES_IN` | 1h | Access token expiration (15m, 1h, 7d, etc.) |
|
|
| `BCRYPT_SALT_ROUNDS` | 10 | Password hash cost (higher = more secure but slower) |
|
|
| `DOMAIN` | http://localhost:5173 | Allowed CORS origin(s), comma-separated (see below) |
|
|
| `COOKIE_SECURE` | auto | Secure flag on auth cookies: `auto`, `true`, `false` |
|
|
| `UV_THREADPOOL_SIZE` | 16 | Concurrent file I/O threads (Node's own default is 4) |
|
|
| `DB_WORKER_COUNT` | 4 | Read-only SQLite query workers (1-16) |
|
|
|
|
Generate secure JWT secret:
|
|
|
|
```bash
|
|
openssl rand -hex 64
|
|
```
|
|
|
|
**COOKIE_SECURE — auth cookies over HTTP and HTTPS:**
|
|
|
|
Browsers discard a cookie marked `Secure` when it arrives over plain HTTP, which
|
|
logs users straight back out. `auto` therefore decides per request: cookies are
|
|
marked `Secure` only on connections that actually used TLS, so one deployment can
|
|
serve a LAN over HTTP and the internet over HTTPS at the same time.
|
|
|
|
Detection reads `X-Forwarded-Proto`, which is trusted only from a proxy. Set
|
|
`COOKIE_SECURE=true` if your TLS-terminating proxy does not send that header, and
|
|
`false` only if you deliberately want the flag off everywhere.
|
|
|
|
**DOMAIN — allowed origins:**
|
|
|
|
`DOMAIN` accepts one origin or a comma-separated list, so a single deployment can
|
|
be reached over several addresses:
|
|
|
|
```bash
|
|
DOMAIN=http://192.168.0.118,https://flashpoint.example.com
|
|
```
|
|
|
|
The first entry is the primary origin, used where a single value is required.
|
|
Requests from any listed origin are accepted, as are requests from hostnames in
|
|
the domains table.
|
|
|
|
Two notes that save debugging time:
|
|
|
|
- Same-origin requests are always allowed, so `SERVE_FRONTEND=true` deployments
|
|
work at any address without listing it here. You only need `DOMAIN` when the UI
|
|
is served from a different origin than the API, or behind a reverse proxy that
|
|
rewrites the `Host` header.
|
|
- Default ports are normalized away: `http://host:80` and `http://host` are
|
|
treated as the same origin, as are `https://host:443` and `https://host`.
|
|
Non-default ports must be written out, for example `http://host:8080`.
|
|
|
|
**Rate Limiting:**
|
|
|
|
| Variable | Default | Description |
|
|
| ------------------------- | ------- | ----------------------- |
|
|
| `RATE_LIMIT_WINDOW_MS` | 60000 | Time window (ms) |
|
|
| `RATE_LIMIT_MAX_REQUESTS` | 100 | Max requests per window |
|
|
|
|
**Logging:**
|
|
|
|
| Variable | Default | Description |
|
|
| ----------- | ------------------------------ | -------------------------------------------- |
|
|
| `LOG_LEVEL` | info | Level: error, warn, info, debug |
|
|
| `LOG_FILE` | `/app/logs/backend.log` (prod) | Log file path (unset in dev = stdout only) |
|
|
|
|
**Database Performance:**
|
|
|
|
| Variable | Default | Description |
|
|
| --------------------- | ----------- | ---------------------------------------------------------------- |
|
|
| `ENABLE_LOCAL_DB_COPY`| false | Copy flashpoint.sqlite locally (for network storage SMB/NFS) |
|
|
| `SQLITE_CACHE_SIZE` | -64000 | SQLite page cache size (negative = KB, -64000 = 64MB) |
|
|
| `SQLITE_MMAP_SIZE` | 268435456 | Memory-mapped I/O size in bytes (256MB) |
|
|
| `ENABLE_CACHE_PREWARM`| true | Pre-load common queries on startup |
|
|
|
|
**Game Content Serving:**
|
|
|
|
| Variable | Default | Description |
|
|
| -------------------- | ------- | ------------------------------------------------ |
|
|
| `ENABLE_CGI` | false | Enable PHP CGI execution for legacy game content |
|
|
|
|
**Frontend Serving:**
|
|
|
|
The backend serves the built React UI in the single-image deployment, so the app
|
|
and API share one origin.
|
|
|
|
| Variable | Default | Description |
|
|
| -------------------- | ----------------------------- | -------------------------------------------------------------- |
|
|
| `SERVE_FRONTEND` | true in production, else false | Serve the built frontend and SPA fallback from the backend |
|
|
| `FRONTEND_DIST_PATH` | `<backend>/../frontend/dist` | Location of the built frontend (rarely needed) |
|
|
| `RUFFLE_DATA_PATH` | `/app/data/ruffle` in production | Where Ruffle is installed. Must sit on a mounted volume, or an in-app update is lost when the container is recreated |
|
|
|
|
**Images and updates:**
|
|
|
|
| Variable | Default | Description |
|
|
| ---------------- | -------- | ------------------------------------------------------------------------------------------------- |
|
|
| `IMAGE_PREFIX` | - | Registry path to pull images from, ending in `/`. Unset builds them from source |
|
|
| `IMAGE_TAG` | `latest` | Image tag to build or pull |
|
|
| `APP_UPDATE_URL` | - | "Latest release" API URL (GitHub or Gitea) that Settings checks for new versions; off when unset |
|
|
|
|
**Streaming:**
|
|
|
|
Games that can't run in a browser, such as Java applets and Shockwave, can be
|
|
streamed by the session manager under `streaming/`. It runs under the
|
|
`streaming` compose profile. See [Streaming](../10-features/13-streaming.md).
|
|
|
|
| Variable | Default | Description |
|
|
| --------------------- | ----------------------------- | --------------------------------------------------------------- |
|
|
| `STREAMING_API_URL` | `http://session-manager:8080` | Session manager's internal API |
|
|
| `STREAMING_STREAM_URL` | `http://session-manager:8081` | Where the app proxies `/stream/` to |
|
|
| `STREAMING_API_TOKEN` | - | Token shared with the session manager. Streaming is off without it |
|
|
|
|
**Trusted Header Login:**
|
|
|
|
See also [Proxy Sign-In](../10-features/14-proxy-sign-in.md).
|
|
|
|
When a reverse proxy such as Authentik (forward auth) authenticates users in
|
|
front of flashpoint-web, it can pass the signed-in username in a header so
|
|
users don't log in twice. The backend believes the header only on connections
|
|
from `TRUSTED_PROXIES`, checked against the connection's own address, not
|
|
`X-Forwarded-For`. The proxy must always set the header, overwriting anything a
|
|
client sends, and flashpoint-web must not be reachable from untrusted networks
|
|
except through it.
|
|
|
|
Users are matched by username, so an existing account of that name is signed
|
|
in; otherwise an account is created (the first one as admin, as with
|
|
registration). New accounts get a random password. While signed in through the
|
|
proxy, users can set a password from Settings without knowing the current one,
|
|
then log in with it when reaching flashpoint-web without the proxy, such as on a
|
|
LAN.
|
|
|
|
| Variable | Default | Description |
|
|
| ------------------------- | ------- | ------------------------------------------------------------------------ |
|
|
| `TRUSTED_HEADER_USERNAME` | - | Header holding the username, e.g. `X-authentik-username` |
|
|
| `TRUSTED_HEADER_EMAIL` | - | Optional header holding the email used for new accounts |
|
|
| `TRUSTED_PROXIES` | - | Comma-separated proxy addresses or CIDR ranges allowed to set the header |
|
|
|
|
With nginx and Authentik's forward auth, each protected `location` needs these
|
|
lines once. Authentik's generated nginx snippet already includes them; adding
|
|
them again sends each header twice:
|
|
|
|
```nginx
|
|
auth_request_set $authentik_username $upstream_http_x_authentik_username;
|
|
auth_request_set $authentik_email $upstream_http_x_authentik_email;
|
|
proxy_set_header X-authentik-username $authentik_username;
|
|
proxy_set_header X-authentik-email $authentik_email;
|
|
```
|
|
|
|
**OpenTelemetry:**
|
|
|
|
| Variable | Default | Description |
|
|
| ------------------------------ | -------------------------- | ---------------------------------------- |
|
|
| `OTEL_ENABLED` | false | Enable distributed tracing and metrics |
|
|
| `OTEL_EXPORTER_OTLP_ENDPOINT` | http://localhost:4318 | OTLP collector endpoint |
|
|
| `OTEL_API_KEY` | - | API key for authentication |
|
|
| `OTEL_SERVICE_NAME` | flashpoint-web | Service name in traces/metrics |
|
|
| `OTEL_TRACES_ENABLED` | true | Enable trace export (when OTEL enabled) |
|
|
| `OTEL_METRICS_ENABLED` | true | Enable metrics export (when OTEL enabled)|
|
|
| `OTEL_METRICS_EXPORT_INTERVAL`| 60000 | Metrics export interval (ms) |
|
|
| `OTEL_LOG_LEVEL` | info | OTEL SDK log level |
|
|
|
|
## Frontend Variables
|
|
|
|
The frontend has no environment variables of its own. API calls use relative
|
|
paths (`/api`), so they resolve against whatever origin serves the app.
|
|
|
|
- **Development**: Vite dev server on port 5173 proxies `/api` to `http://localhost:3100`
|
|
- **Production**: The backend serves the built UI and the API from the same origin
|
|
|
|
## Docker Environment Variables
|
|
|
|
Location: `.env` in project root (used by docker-compose)
|
|
|
|
**Required:**
|
|
|
|
| Variable | Description |
|
|
| ---------------------- | --------------------------------------------------------- |
|
|
| `FLASHPOINT_HOST_PATH` | Host path to Flashpoint installation (bind-mounted as ro) |
|
|
| `JWT_SECRET` | Secret for JWT signing (generate with `openssl rand -hex 64`) |
|
|
|
|
**Port Mapping:**
|
|
|
|
| Variable | Default | Description |
|
|
| ---------- | ------- | ------------------------------------------------------ |
|
|
| `WEB_PORT` | 80 | Host port mapped to the container (serves UI + API) |
|
|
|
|
**Container Settings:**
|
|
|
|
| Variable | Default | Description |
|
|
| ----------- | ------- | ---------------------------------------------------- |
|
|
| `PUID` | 1000 | Container user ID (match host user: `id -u`) |
|
|
| `PGID` | 1000 | Container group ID (match host user: `id -g`) |
|
|
| `TZ` | UTC | Container timezone |
|
|
| `IMAGE_TAG` | latest | Docker image tag (production compose only) |
|
|
| `DATA_PATH` | ./data | Host path for persistent data (production compose) |
|
|
| `LOGS_PATH` | ./logs | Host path for log files |
|
|
|
|
All backend variables listed above are also passable via docker-compose. See
|
|
`docker-compose.yml` for the full list with defaults.
|
|
|
|
## Docker Compose Setup
|
|
|
|
**Create .env file:**
|
|
|
|
```bash
|
|
cat > .env << EOF
|
|
FLASHPOINT_HOST_PATH=/path/to/flashpoint
|
|
JWT_SECRET=$(openssl rand -hex 64)
|
|
DOMAIN=https://flashpoint.example.com
|
|
WEB_PORT=80
|
|
LOG_LEVEL=warn
|
|
EOF
|
|
```
|
|
|
|
**Start services:**
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
## Environment Templates
|
|
|
|
**Development (`backend/.env`):**
|
|
|
|
```bash
|
|
NODE_ENV=development
|
|
FLASHPOINT_PATH=D:/Flashpoint
|
|
JWT_SECRET=development-secret-change-in-production
|
|
DOMAIN=http://localhost:5173
|
|
RATE_LIMIT_MAX_REQUESTS=1000
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
**Production (`.env` for Docker):**
|
|
|
|
```bash
|
|
FLASHPOINT_HOST_PATH=/data/flashpoint
|
|
JWT_SECRET=CHANGE-THIS-TO-A-RANDOM-64-CHARACTER-STRING
|
|
DOMAIN=https://flashpoint.example.com
|
|
WEB_PORT=80
|
|
LOG_LEVEL=warn
|
|
```
|
|
|
|
## Validation and Defaults
|
|
|
|
**Required Variables:**
|
|
|
|
**Backend (local dev):**
|
|
|
|
- `FLASHPOINT_PATH` (only this is required; others auto-derive)
|
|
|
|
**Docker Production:**
|
|
|
|
- `FLASHPOINT_HOST_PATH` (must point to Flashpoint installation)
|
|
- `JWT_SECRET` (must be changed from default)
|
|
|
|
**Verify configuration:**
|
|
|
|
```bash
|
|
cd backend
|
|
node -e "require('dotenv').config(); console.log(process.env.FLASHPOINT_PATH)"
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
1. Never commit .env files to version control
|
|
2. Use strong JWT secrets (64+ characters) in production
|
|
3. Restrict CORS origins to your domain only (no wildcards)
|
|
4. Use HTTPS in production (update DOMAIN to https://)
|
|
5. Limit exposed ports (don't expose all services)
|
|
6. Rotate secrets periodically
|
|
7. Use environment-specific files (.env.production, .env.development)
|
|
8. Store secrets in secure management system (AWS Secrets Manager, HashiCorp
|
|
Vault)
|
|
9. Use read-only mounts for Flashpoint data in Docker
|
|
|
|
## Next Steps
|
|
|
|
- [Docker Deployment](./docker-deployment.md)
|
|
- [Security Considerations](./security-considerations.md)
|