-
Notifications
You must be signed in to change notification settings - Fork 0
Configuration Guide
Sergio Soto edited this page Mar 25, 2026
·
3 revisions
SpaceHarbor is configured through environment variables. This guide documents every configuration option, grouped by category.
-
.env.examplein the repo root contains all common configuration options with documented defaults. Copy it to.envand edit for your environment. -
docker-compose.yml injects env vars into containers. Three variables are required and will hard-fail on startup if missing:
SPACEHARBOR_JWT_SECRET,SPACEHARBOR_ADMIN_EMAIL,SPACEHARBOR_ADMIN_PASSWORD. -
Advanced/internal variables (marked below) are not in
.env.exampleand are typically only needed for specialized deployments.
Quick path: Copy
.env.example→.env, set the three required variables, rundocker compose up. See Quick Start for details.
These must be set for any deployment. Docker Compose will refuse to start without them.
| Variable | Purpose | Example |
|---|---|---|
SPACEHARBOR_JWT_SECRET |
JWT signing secret. Generate: openssl rand -base64 32
|
a3Bf9x... |
SPACEHARBOR_ADMIN_EMAIL |
Bootstrap super_admin email | admin@studio.com |
SPACEHARBOR_ADMIN_PASSWORD |
Bootstrap super_admin password. Rotate after first login. | <strong-password> |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_IAM_ENABLED |
true (compose) / false (.env.example) |
Master switch for IAM (auth + RBAC). Must be true in production. |
SPACEHARBOR_IAM_SHADOW_MODE |
false |
Log authorization decisions without enforcing. Set to false in production. |
SPACEHARBOR_REQUIRE_TLS |
true in production, false in dev |
Enforce HTTPS via X-Forwarded-Proto. Set to false only for local dev. |
SPACEHARBOR_ALLOW_INSECURE_MODE |
false |
Permit running without IAM and VAST Database outside dev mode. |
SPACEHARBOR_ALLOW_REGISTRATION |
false |
Enable self-registration endpoint (POST /auth/register). |
SPACEHARBOR_API_KEY |
(empty) | Shared API key for all services. Empty = auth disabled. |
SPACEHARBOR_API_KEY_CONTROL_PLANE |
(empty) | Per-service key for control-plane. |
SPACEHARBOR_API_KEY_MEDIA_WORKER |
(empty) | Per-service key for media-worker. |
SPACEHARBOR_API_KEY_SCANNER |
(empty) | Per-service key for scanner-function. |
SPACEHARBOR_API_KEY_OPENASSETIO |
(empty) | Per-service key for openassetio-manager. |
NODE_ENV |
development |
Runtime environment. Controls TLS enforcement and IAM behavior. |
Note:
SPACEHARBOR_API_KEYSis assembled automatically by docker-compose from the four per-service keys. In non-compose deployments, set it as a comma-separated list manually.
Configure to accept JWT tokens from an external Identity Provider. See Identity and Access for setup details.
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_OIDC_ISSUER |
(empty) | OIDC issuer URL (e.g., https://idp.example.com/realms/spaceharbor) |
SPACEHARBOR_OIDC_AUDIENCE |
(empty) | Expected JWT aud claim. Prevents cross-service token reuse. |
SPACEHARBOR_OIDC_JWKS_URI |
(empty) | JWKS endpoint for token verification. Required for production OIDC. |
SPACEHARBOR_SCIM_TOKEN |
(empty) | Bearer token for SCIM 2.0 inbound user/group provisioning. |
These are not in .env.example. Only needed for advanced OIDC group mapping or JIT provisioning.
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_IAM_DEFAULT_ROLE |
viewer |
Default role for JIT-provisioned users. |
SPACEHARBOR_IAM_GROUP_ROLE_MAP |
{} |
JSON mapping of OIDC groups to roles (e.g., {"vfx-supers":"supervisor"}). |
SPACEHARBOR_DEFAULT_PROJECT |
default |
Project for JIT user role assignment. |
SPACEHARBOR_API_KEY_MAX_AGE_DAYS |
365 |
API key expiration in days. |
SPACEHARBOR_SERVICE_TOKEN |
(empty) | Service-to-service bearer token. Grants admin privileges. |
SpaceHarbor stores persistent data in VAST Database via a Trino-compatible SQL endpoint.
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_PERSISTENCE_BACKEND |
local |
local (in-memory) or vast (VAST Database). |
VAST_DATABASE_URL |
(empty) | VAST Database connection URL. Empty = local-only mode. |
VAST_DB_ENDPOINT |
(empty) | VAST Database SQL endpoint (e.g., https://<VAST_VIP>:8443). |
VAST_DB_USERNAME |
(empty) | VAST Database credentials (S3 access key). |
VAST_DB_PASSWORD |
(empty) | VAST Database credentials (S3 secret key). |
VAST_ACCESS_KEY |
(empty) | VAST S3 access key (fallback for DB credentials). |
VAST_SECRET_KEY |
(empty) | VAST S3 secret key (fallback for DB credentials). |
SPACEHARBOR_VAST_STRICT |
false |
Reject operations if VAST Database is unreachable. |
SPACEHARBOR_VAST_FALLBACK_TO_LOCAL |
true |
Fall back to local adapter when VAST is unavailable. |
Credential note: VAST Database uses S3 access key pairs for authentication. Generate them in VMS > Users > Access Keys.
Deprecated:
VAST_TRINO_ENDPOINT,VAST_TRINO_USERNAME,VAST_TRINO_PASSWORDare still accepted as fallbacks but will be removed in v0.3.0. See ADR-008 for the deprecation plan.
| Variable | Default | Purpose |
|---|---|---|
VAST_SCHEMA |
spaceharbor/production |
SQL schema path for SpaceHarbor tables. |
VAST_CATALOG_TABLE |
vast_catalog.default.catalog |
VAST Catalog table reference for file index queries. |
SpaceHarbor consumes workflow completion events from VAST Event Broker.
| Variable | Default | Purpose |
|---|---|---|
VAST_EVENT_BROKER_URL |
(empty) | Kafka broker URL. Leave empty to disable event subscription. |
VAST_EVENT_BROKER_TOPIC |
spaceharbor.dataengine.completed |
Kafka topic for DataEngine completion events. |
VAST_EVENT_BROKER_GROUP |
spaceharbor-control-plane |
Kafka consumer group ID. |
VAST_EVENT_BROKER_SSL |
true |
Enable SSL for Kafka. Must be true in production.
|
VAST_EVENT_BROKER_SASL_USERNAME |
(empty) | SASL username (VAST local user). |
VAST_EVENT_BROKER_SASL_PASSWORD |
(empty) | SASL password. |
VAST_EVENT_BROKER_SASL_MECHANISM |
PLAIN |
SASL mechanism. Also supports SCRAM-SHA-256, SCRAM-SHA-512. |
Security: Never use
PLAINwithout SSL enabled — credentials would be sent in cleartext.
Create a VAST local user for Kafka:
vastcmd user create --name spaceharbor-kafka --password <secure> --localSpaceHarbor orchestrates VAST DataEngine for media processing functions.
| Variable | Default | Purpose |
|---|---|---|
VAST_DATAENGINE_URL |
(empty) | DataEngine REST API endpoint. Required for DataEngine functions. |
VAST_API_TOKEN |
(empty) | VAST API authentication token. |
VAST_API_KEY |
(empty) | VAST API key for DataEngine function Authorization headers. |
See Pipeline and Functions for function registration and configuration.
S3-compatible object storage for media assets (thumbnails, proxies, uploads).
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_S3_ENDPOINT |
(empty) | S3 endpoint URL (VAST S3 or AWS). Required for S3 storage. |
SPACEHARBOR_S3_BUCKET |
(empty) | S3 bucket name for media storage. |
SPACEHARBOR_S3_REGION |
us-east-1 |
S3 region. |
SPACEHARBOR_S3_ACCESS_KEY_ID |
(empty) | S3 access key. Sensitive — do not commit. |
SPACEHARBOR_S3_SECRET_ACCESS_KEY |
(empty) | S3 secret key. Sensitive — do not commit. |
All five must be set for S3 to be available. If any are missing, S3 storage is disabled.
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_NFS_VIP |
(empty) | NFS server VIP for access URI resolution. |
SPACEHARBOR_SMB_SERVER |
(empty) | SMB/CIFS server hostname for Windows path resolution. |
SPACEHARBOR_MEDIA_BASE_DIR |
/data/media |
Base directory for mounted media volumes (DataEngine functions). |
SPACEHARBOR_LUT_BASE_DIR |
/data/luts |
Base directory for LUT (color transform) files. |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_CORS_ORIGIN |
http://localhost:4173 |
Single CORS origin for SSE event stream. |
SPACEHARBOR_CORS_ORIGINS |
(empty) | Comma-separated additional CORS origins. |
Development mode automatically allows localhost:4173, localhost:4174, and localhost:5173.
| Variable | Default | Purpose |
|---|---|---|
PORT |
8080 |
HTTP server bind port. |
HOST |
0.0.0.0 |
HTTP server bind address. |
LOG_LEVEL |
info |
Fastify logger level (debug, info, warn, error). |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_BASE_URL |
(auto-inferred) | Base URL for device authorization flow. Inferred from request if not set. |
SPACEHARBOR_IDENTITY_ENFORCEMENT |
relaxed |
Legacy auth mode. Superseded by IAM module. |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_WEBHOOK_SLACK_URL |
(empty) | Slack webhook URL. Leave empty to disable. |
SPACEHARBOR_WEBHOOK_TEAMS_URL |
(empty) | Microsoft Teams webhook URL. |
SPACEHARBOR_WEBHOOK_PRODUCTION_URL |
(empty) | Custom production webhook URL. |
SPACEHARBOR_WEBHOOK_SIGNING_SECRET |
(empty) | HMAC secret for webhook payload signing. Required when strict mode is on. |
SPACEHARBOR_WEBHOOK_STRICT_MODE |
false |
Require all webhook targets + signing secret. |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_MAX_JOB_ATTEMPTS |
3 |
Max retry attempts before DLQ. |
SPACEHARBOR_REPLAY_ENABLED |
true |
Enable job replay endpoint. |
SPACEHARBOR_REPLAY_MAX_PER_MINUTE |
60 |
Rate limit for job replays. |
SPACEHARBOR_LEASE_REAPING_ENABLED |
true |
Enable background reaping of expired worker leases. |
SPACEHARBOR_LEASE_REAPING_INTERVAL_SECONDS |
30 |
Interval between reaping sweeps. |
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_AUDIT_RETENTION_ENABLED |
true |
Enable automatic audit log retention. |
SPACEHARBOR_AUDIT_RETENTION_MODE |
dry-run |
dry-run (log only) or apply (delete old records). |
SPACEHARBOR_AUDIT_RETENTION_DAYS |
90 |
Retention window in days. |
SPACEHARBOR_AUDIT_RETENTION_INTERVAL_SECONDS |
86400 |
Sweep interval (default: 24 hours). |
SPACEHARBOR_AUDIT_RETENTION_MAX_DELETE_PER_RUN |
(unlimited) | Max records per sweep. |
The media-worker polls the control-plane for jobs (development mode only — production uses VAST DataEngine directly).
| Variable | Default | Purpose |
|---|---|---|
CONTROL_PLANE_URL |
http://localhost:8080 |
Control-plane URL for job polling. |
CONTROL_PLANE_API_KEY |
(empty) | API key for worker → control-plane auth. |
WORKER_ID |
media-worker-1 |
Worker instance identifier. |
WORKER_POLL_SECONDS |
2 |
Job polling interval. |
WORKER_LEASE_SECONDS |
30 |
Job lease duration. |
WORKER_JOB_TIMEOUT_SECONDS |
300 |
Max job execution time (5 minutes). |
| Variable | Default | Purpose |
|---|---|---|
VITE_API_BASE_URL |
http://localhost:8080 |
Control-plane API URL. Baked into JS bundle at build time. |
Security: Never use
VITE_prefix for secrets — they are embedded in the client-side JavaScript bundle.
| Variable | Default | Purpose |
|---|---|---|
OPENASSETIO_MANAGER_URL |
http://openassetio-manager:8001 |
Manager service URL. |
OPENASSETIO_DEV_MODE |
false |
Skip control-plane auth, use local test data. |
VAST_DB_HOST |
(empty) | Direct VAST Database hostname for the manager. |
VAST_DB_PORT |
8080 |
Direct VAST Database port. |
These variables are used by the Python DataEngine function containers.
| Variable | Default | Purpose |
|---|---|---|
KAFKA_BROKER |
vastbroker:9092 |
Kafka broker for function output events. |
DEV_MODE |
false |
Skip VAST I/O, use local test files. |
TRANSCODE_PROFILE |
h264_review |
FFmpeg transcode profile name. |
VAST_OUTPUT_PATH |
(empty) | Output path for transcoded files. |
OCIO_CONFIG_PATH |
(ACES 1.3 system path) | OpenColorIO config file path. |
Optional function-specific variables: LUT_PATH, AUDIO_SOURCE_PATH, TIMECODE_START, BURN_IN_TEXT.
| Variable | Default | Purpose |
|---|---|---|
SPACEHARBOR_EVENT_DEDUP_SIZE |
10000 |
Event dedup cache size (local persistence only). |
SPACEHARBOR_EVENT_DEDUP_TTL_HOURS |
24 |
Event dedup TTL in hours (local persistence only). |
VAST_S3_BUCKET |
spaceharbor-media |
S3 bucket for storage-metrics-collector. |
VAST_S3_ENDPOINT |
(empty) | VAST S3 endpoint for storage-metrics-collector. |
| Variable | Default | Purpose |
|---|---|---|
VAST_DB_INTEGRATION |
false |
Enable VAST Database integration tests. |
After configuration changes, verify the system:
# Health check
curl http://localhost:8080/health
# Run configuration consistency check
node scripts/ci/check-docs-consistency.js- Quick Start — Get running in 5 minutes
- Installation Guide — Full installation options
- Deployment Guide — Production deployment procedures
- Identity and Access — Authentication and RBAC details
- Storage Connectors — Storage protocol details
- VAST Cluster Configuration Guide — End-to-end VAST integration (Database, Catalog, Event Broker, DataEngine, Audit)
SpaceHarbor — VAST-Native Media Asset Management | Report an Issue | Apache 2.0
- Deployment Guide
- Configuration Guide
- VAST Cluster Configuration
- Monitoring & Observability
- Troubleshooting
- Workflow Canvas
- Naming Templates
- Metadata Pipelines
- Plugins (Export/Import)
- Scanner Forwarder
- Asset Metadata