Configuration
Every environment variable Velic reads, grouped and documented from the real schema.
Velic is configured entirely through environment variables, validated once at
startup against a typed schema. Copy .env.example to .env and fill it in;
an incomplete or invalid configuration fails fast with a readable error.
Never commit secrets
The values below are documented by name and purpose only. Generate your own
secrets and keys, and keep .env out of version control.
Runtime
| Variable | Default | Description |
|---|---|---|
NODE_ENV | development | development, test, or production. |
LOG_LEVEL | info | fatal, error, warn, info, debug, trace, or silent. |
API server
| Variable | Default | Description |
|---|---|---|
API_HOST | 0.0.0.0 | Bind address for the API. |
API_PORT | 4000 | API port. |
API_PUBLIC_URL | http://localhost:4000 | Public base URL the web app uses to reach the API. |
WEB_ORIGIN | http://localhost:5173 | Allowed CORS origin for the web app. |
App secrets
| Variable | Required | Description |
|---|---|---|
APP_SESSION_SECRET | Yes | Signs session cookies. Minimum 32 characters. |
APP_DOWNLOAD_URL_SECRET | Yes | Signs short-lived restore/download URLs. Minimum 32 characters. |
Generate each with openssl rand -hex 32.
Postgres
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | None (required) | Postgres connection string. |
DATABASE_POOL_MAX | 10 | Maximum pool connections. |
Redis
| Variable | Default | Description |
|---|---|---|
REDIS_URL | redis://localhost:6379 | Redis connection (used by the BullMQ queues and the session cache). |
MinIO / S3 staging
Resumable uploads are staged here as ciphertext before being chunked and stored on Filecoin.
| Variable | Default | Description |
|---|---|---|
S3_ENDPOINT | http://localhost:9000 | S3-compatible endpoint (MinIO locally). |
S3_REGION | us-east-1 | Region. |
S3_BUCKET | velic-staging | Staging bucket. |
S3_ACCESS_KEY_ID | None (required) | Access key. |
S3_SECRET_ACCESS_KEY | None (required) | Secret key. |
S3_FORCE_PATH_STYLE | true | Path-style addressing (MinIO requires it). |
Filecoin / chain
| Variable | Default | Description |
|---|---|---|
CHAIN | calibration | calibration (314159) or mainnet (314). |
RPC_URL | Glif Calibration RPC | Filecoin JSON-RPC endpoint. |
RPC_WS_URL | None (optional) | Optional WebSocket RPC for subscriptions. |
SYNAPSE_SOURCE | velic | Dataset namespace tag; datasets are reused only when it matches. |
Contract addresses are not configured by hand
The FWSS, PDPVerifier, Filecoin Pay, and USDFC contract addresses are resolved at init from the installed Synapse packages. They are intentionally not environment variables, so they cannot drift from the SDK you actually run.
Operator signer
All signer backends are real (no mocks). Select one with SIGNER_BACKEND.
| Variable | Default | Description |
|---|---|---|
SIGNER_BACKEND | local | local, kms, or turnkey. |
OPERATOR_KEYSTORE_PATH | None | Encrypted JSON keystore (preferred for local). |
OPERATOR_KEYSTORE_PASSWORD | None | Passphrase for the keystore. |
OPERATOR_PRIVATE_KEY | None | Raw 0x private key (dev convenience only). |
TURNKEY_API_BASE_URL | https://api.turnkey.com | Turnkey API base URL. |
TURNKEY_API_PUBLIC_KEY | None | Required when SIGNER_BACKEND=turnkey. |
TURNKEY_API_PRIVATE_KEY | None | Required when SIGNER_BACKEND=turnkey. |
TURNKEY_ORGANIZATION_ID | None | Required when SIGNER_BACKEND=turnkey. |
TURNKEY_SIGN_WITH | None | Required when SIGNER_BACKEND=turnkey. |
For local, provide either a keystore (path + password) or
OPERATOR_PRIVATE_KEY.
KMS (encryption-key wrapping)
Wraps the per-master AES data-encryption keys; can also back the signer.
| Variable | Default | Description |
|---|---|---|
KMS_PROVIDER | local | local, aws, or gcp. |
KMS_LOCAL_MASTER_KEY | None | Base64 32-byte master key (required when KMS_PROVIDER=local). Generate with openssl rand -base64 32. |
KMS_KEY_ID | None | Cloud KMS key id/ARN (required for aws/gcp, or SIGNER_BACKEND=kms). |
KMS_REGION | None | Cloud KMS region. |
Media tooling
Invoked as separate-process binaries (LGPL FFmpeg; pinned c2patool).
| Variable | Default | Description |
|---|---|---|
FFMPEG_PATH | ffmpeg | FFmpeg binary (thumbnail frames only, no transcoding). |
FFPROBE_PATH | ffprobe | FFprobe binary (technical metadata). |
MEDIAINFO_PATH | mediainfo | MediaInfo binary (optional metadata enrichment). |
C2PATOOL_PATH | None (optional) | Leave unset to use the pinned, vendored c2patool; or set an absolute path. |
Worker
| Variable | Default | Description |
|---|---|---|
WORKER_CONCURRENCY | 4 | Concurrent jobs per worker process. |
Transactional email
Powers password-reset and team-invite links.
| Variable | Default | Description |
|---|---|---|
SMTP_HOST | None (optional) | SMTP relay host (e.g. Brevo). |
SMTP_PORT | 587 | 587 = STARTTLS, 465 = implicit TLS. |
SMTP_SECURE | false | true for implicit TLS (port 465). |
SMTP_USER | None | Required when SMTP_HOST is set. |
SMTP_PASSWORD | None | Required when SMTP_HOST is set. |
EMAIL_FROM | None | Required when SMTP_HOST is set; must be a verified sender. |
EMAIL_REPLY_TO | None | Reply-To address (a real inbox). |
Email console fallback
When SMTP_HOST is unset, the email module uses a clearly-logged console
fallback so local development works without a relay. It never silently
pretends to deliver a message.
No billing variables
Billing is not part of this build, so there are intentionally no Stripe or payment variables. The on-chain treasury settles operator-side; see the architecture.