Environment Variables

July 3, 2026 · View on GitHub

This document lists all environment variables used by WorkAdventure services. These variables are defined in the .env file.

⚠️ Auto-generated file - Do not edit manually. Run npm run generate-env-docs to update.

Play Service

Environment variables for the Play service (frontend and pusher).

VariableRequiredDescription
SECRET_KEYYesSecret key used to encode JWT tokens. Set this to a random unguessable string.
API_URLYesURL of the back server API
ADMIN_API_URLNoThe URL to the admin API. If in the same network, you can use a local name here.
ADMIN_URLNoThe URL to the admin. This should be a publicly accessible URL.
ADMIN_BO_URLNoThe URL to the admin dashboard. Will be used to redirect the user to the admin dashboard. You can put it a URL that will automatically connect the user.
ADMIN_API_TOKENNoAuthentication token for the admin API
AUTOLOGIN_URLNoThe URL to be used to automatically log someone given a token.
ADMIN_SOCKETS_TOKENNoAuthentication token to connect to 'play' admin websocket endpoint. This endpoint is typically used to list users connected to a given room.
CPU_OVERHEAT_THRESHOLDNoCPU usage threshold (in %) that triggers performance warnings. Defaults to 80
PUSHER_HTTP_PORTNoHTTP port for the pusher service. Defaults to 3000
PUSHER_WS_PORTNoWebSocket port for the pusher service. Defaults to 3001
SOCKET_IDLE_TIMERNomaximum time (in second) without activity before a socket is closed. Should be greater than 60 seconds in order to cope for Chrome intensive throttling (https://developer.chrome.com/blog/timer-throttling-in-chrome-88/#intensive-throttling)
CLIENT_DISCONNECTION_RETENTION_MSNoMaximum time, in milliseconds, the client keeps sent websocket messages for replay after a short disconnection. Defaults to 30000.
PUSHER_ADMIN_WS_MAX_BACKPRESSURE_BYTESNoMaximum uWebSockets backpressure bytes accepted on admin websocket connections. Defaults to 1048576.
VITE_URLNoURL of the Vite development server (development only)
ALLOWED_CORS_ORIGINNoAllowed CORS origin for API requests. Use '*' to allow any domain
PUSHER_URLNoPublic URL of the pusher service
FRONT_URLNoPublic URL of the frontend application
MAP_STORAGE_API_TOKENYesAPI token for authenticating with the map-storage service
REDIS_HOSTNoRedis server hostname or IP address
REDIS_PORTNoRedis server port. Defaults to 6379
REDIS_PASSWORDNoRedis authentication password
PUBLIC_MAP_STORAGE_URLNoThe public URL to the map-storage server (for instance: "https://map-storage.example.com")
INTERNAL_MAP_STORAGE_URLNoThe internal URL to the map-storage server (for instance: "https://map-storage:3000")
OPENID_CLIENT_IDNoOAuth2 client ID for OpenID Connect authentication
OPENID_CLIENT_SECRETNoOAuth2 client secret for OpenID Connect authentication
OPENID_CLIENT_ISSUERNoOpenID Connect issuer URL (identity provider)
OPENID_CLIENT_REDIRECT_URLNoOAuth2 redirect URL after successful authentication
OPENID_CLIENT_REDIRECT_LOGOUT_URLNoRedirect URL after user logout
OPENID_PROFILE_SCREEN_PROVIDERNoURL of the 'profile' page (typically part of the optionnal Admin component)
OPENID_SCOPENoOAuth2 scopes to request (space-separated). Defaults to 'openid email profile'
OPENID_PROMPTNoOpenID Connect prompt parameter (e.g., 'login', 'consent')
OPENID_USERNAME_CLAIMNoJWT claim to use as the username. Defaults to 'preferred_username'
OPENID_LOCALE_CLAIMNoJWT claim to use for user locale. Defaults to 'locale'
OPENID_WOKA_NAME_POLICYNoPolicy for avatar naming: 'user_input' or 'openid_nickname'
OPENID_TAGS_CLAIMNoJWT claim containing user tags/roles
DISABLE_ANONYMOUSNoIf true, anonymous users cannot access the platform. Defaults to false
PROMETHEUS_AUTHORIZATION_TOKENNoThe token to access the Prometheus metrics.
PROMETHEUS_PORTNoThe port to access the Prometheus metrics. If not set, the default port is used AND an authorization token is required.
ENABLE_CHATNoEnable/disable the chat feature. Defaults to true
ENABLE_CHAT_UPLOADNoEnable/disable file upload in chat. Defaults to true
ENABLE_CHAT_ONLINE_LISTNoEnable/disable online users list in chat. Defaults to true
ENABLE_CHAT_DISCONNECTED_LISTNoEnable/disable offline users list in chat. Defaults to true
DEFAULT_WOKA_NAMENoDefault name to use for users when they join the room.
DEFAULT_WOKA_TEXTURENoDefault avatar texture URL to use for users.
SKIP_CAMERA_PAGENoWhether to skip the camera permission request page. Defaults to false.
BYPASS_PWANoWhen true, LocalAdmin map details set bypassPwa so the client never shows the Web App install flow. Defaults to false.
PROVIDE_DEFAULT_WOKA_NAMENoHow woka names are assigned: 'no' (manual input), 'random' (random name), 'fix' (use DEFAULT_WOKA_NAME), 'fix-plus-random-numbers' (use DEFAULT_WOKA_NAME with random numbers appended).
PROVIDE_DEFAULT_WOKA_TEXTURENoHow woka textures/avatars are assigned: 'no' (manual selection), 'random' (random texture), 'fix' (use DEFAULT_WOKA_TEXTURE).
ENABLE_SAYNoWhether the users can communicate via comics-style bubbles.
ENABLE_ISSUE_REPORTNoWhether the feature 'issue report' is enabled or not on this room. Defaults to true.
ENABLE_TUTORIALNoWhether the onboarding tutorial is enabled or not on this room. Defaults to true.
ENABLE_OPENAPI_ENDPOINTNoEnable/disable the OpenAPI documentation endpoint. Defaults to false
VIDEO_ANALYTICS_FLUSH_INTERVAL_MSNoInterval in milliseconds between video quality analytics batch flushes. Defaults to 10000
VIDEO_ANALYTICS_TIMEOUT_MSNoHTTP timeout in milliseconds for video quality analytics ingestion calls. Defaults to 2000
VIDEO_ANALYTICS_MAX_QUEUE_SIZENoMaximum number of video quality samples queued in pusher memory. Defaults to 10000
VIDEO_ANALYTICS_MAX_BATCH_SIZENoMaximum number of video quality samples sent in one admin batch. Defaults to 1000
START_ROOM_URLNoDefault room URL where users start when accessing the platform
DEBUG_MODENoEnable debug mode with additional console logging. Defaults to false
UPLOADER_URLYesURL of the file uploader service
ICON_URLYesBase URL for icon resources
STUN_SERVERNoComma separated list of STUN server URLs for WebRTC NAT traversal (format: 'stun:hostname:port')
TURN_SERVERNoComma separated list of TURN server URLs for WebRTC relay (format: 'turn:hostname:port')
SKIP_RENDER_OPTIMIZATIONSNoSkip rendering optimizations (useful for debugging). Defaults to false
DISABLE_NOTIFICATIONSNoDisable browser notifications. Defaults to false
TURN_USERNoUsername for TURN server authentication
TURN_PASSWORDNoPassword for TURN server authentication
TURN_STATIC_AUTH_SECRETNoThe auth secret to generate TURN credentials on the fly (enabled by the --use-auth-secret and --auth-secret in Coturn).
TURN_CREDENTIALS_RENEWAL_TIMENoTime interval (in milliseconds) for renewing TURN server credentials. Defaults to 10800000 milliseconds (3 hours)
JITSI_URLNoURL of the Jitsi Meet server for video conferencing
JITSI_PRIVATE_MODENoIf true, Jitsi rooms are private and require authentication. Defaults to false
MAX_USERNAME_LENGTHNoMaximum allowed length for usernames. Defaults to 10
MAX_PER_GROUPNoMaximum number of users in a bubble/group. Defaults to 4
MAX_DISPLAYED_VIDEOSNoAn approximation of the maximum number of videos displayed at once. If there are more videos to display, the user will have to scroll. The number of videos can sometimes be slightly greater (MAX_DISPLAYED_VIDEOS + number of videos to display % number of videos per row). This is useful to avoid overloading the Livekit server when a lot of people are in the same room.
NODE_ENVNoNode.js environment: 'development', 'production', or 'test'
CONTACT_URLNoURL for users to contact support or administrators
POSTHOG_API_KEYNoPostHog API key for analytics tracking
POSTHOG_URLYesPostHog server URL for analytics. Defaults to PostHog cloud
FALLBACK_LOCALENoDefault locale/language code when user's locale is not available (e.g., 'en', 'fr')
ENABLE_REPORT_ISSUES_MENUNoEnable the 'Report Issues' menu option. Defaults to false
REPORT_ISSUES_URLYesURL where users can report issues (e.g., GitHub issues, support portal)
LOGROCKET_IDNoLogRocket application ID for session recording and monitoring
SENTRY_DSN_FRONTNoSentry DSN for frontend error tracking
SENTRY_DSN_PUSHERNoSentry DSN for pusher service error tracking
SENTRY_RELEASENoSentry release version identifier for error tracking
SENTRY_ENVIRONMENTNoSentry environment name (e.g., 'production', 'staging', 'development')
SENTRY_TRACES_SAMPLE_RATENoThe sampling rate for Sentry traces. Only used if SENTRY_DSN is configured. Defaults to 0.1
ROOM_API_BIND_HOSTNoBind host for the Room API gRPC server. Defaults to [::].
ROOM_API_PORTNoPort for the Room API gRPC server. Defaults to 50051
ROOM_API_SECRET_KEYNoSecret key for Room API authentication
ENABLE_MAP_EDITORNoEnable the built-in map editor. Defaults to false
MAP_EDITOR_ALLOWED_USERSNoComma-separated list of user IDs allowed to edit maps
MAP_EDITOR_ALLOW_ALL_USERSNoIf set to true, all users can edit the map. If set to false, only the users in MAP_EDITOR_ALLOWED_USERS or users with the "admin" or "editor" tag can edit the map. Note: this setting is ignored if an Admin API is configured.
WOKA_SPEEDNoAvatar (WOKA) movement speed. Defaults to 9
FEATURE_FLAG_BROADCAST_AREASNoEnable broadcast areas feature. Defaults to false
KLAXOON_ENABLEDNoEnable Klaxoon embedded application integration. Defaults to false
KLAXOON_CLIENT_IDNoKlaxoon OAuth2 client ID
YOUTUBE_ENABLEDNoEnable YouTube map editor tool. Defaults to false
GOOGLE_DRIVE_ENABLEDNoEnable Google Drive map editor tool. Defaults to false
GOOGLE_DOCS_ENABLEDNoEnable Google Docs map editor tool. Defaults to false
GOOGLE_SHEETS_ENABLEDNoEnable Google Sheets map editor tool. Defaults to false
GOOGLE_SLIDES_ENABLEDNoEnable Google Slides map editor tool. Defaults to false
ERASER_ENABLEDNoEnable Eraser.io embedded whiteboard. Defaults to false
EXCALIDRAW_ENABLEDNoEnable Excalidraw embedded whiteboard. Defaults to false
EXCALIDRAW_DOMAINSNoComma-separated list of allowed Excalidraw domains
EMBEDDED_DOMAINS_WHITELISTNoComma-separated list of domains allowed for embedded iframes
CARDS_ENABLEDNoEnable Cards embedded application. Defaults to false
TLDRAW_ENABLEDNoEnable tldraw embedded whiteboard. Defaults to false
MINIMUM_DISTANCENoMinimum distance (in pixels) before users are considered to be in proximity. Defaults to 64
GOOGLE_DRIVE_PICKER_CLIENT_IDNoGoogle OAuth2 client ID for Drive Picker
GOOGLE_DRIVE_PICKER_API_KEYNoGoogle API key for Drive Picker
GOOGLE_DRIVE_PICKER_APP_IDNoGoogle application ID for Drive Picker
LIVEKIT_PIXEL_DENSITYNoPixel density multiplier for LiveKit adaptive streams. 1 means LiveKit will use a better simulcast layer as soon as the video box is bigger than the stream. Lower values delay upgrades to larger simulcast layers. Defaults to 0.666666 (i.e. allow a 50% upscale of the video before switching to the higher simulcast layer)
MATRIX_API_URINoMatrix homeserver API URI (internal)
MATRIX_PUBLIC_URINoMatrix homeserver public URI
MATRIX_ADMIN_USERNoMatrix administrator username
MATRIX_ADMIN_PASSWORDNoMatrix administrator password
MATRIX_DOMAINNoMatrix server domain
EMBEDLY_KEYNoEmbedly API key for rich link previews
GRPC_MAX_MESSAGE_SIZEYesThe maximum size of a gRPC message. Defaults to 20 MB.
LIVEKIT_RECORDING_S3_ENDPOINTNoThe S3 endpoint for Livekit recording.
LIVEKIT_RECORDING_S3_ACCESS_KEYNoThe S3 access key for Livekit recording.
LIVEKIT_RECORDING_S3_SECRET_KEYNoThe S3 secret key for Livekit recording.
LIVEKIT_RECORDING_S3_BUCKETNoThe S3 bucket for Livekit recording.
LIVEKIT_RECORDING_S3_REGIONNoThe S3 region for Livekit recording.
LIVEKIT_RECORDING_S3_CDN_ENDPOINTNoThe S3 CDN endpoint for Livekit recording.
BACKGROUND_TRANSFORMER_ENGINENoVirtual background transformer engine: 'tasks-vision' (GPU-accelerated, experimental) or 'selfie-segmentation' (CPU-based, stable). Currently defaults to 'selfie-segmentation'; 'tasks-vision' is intended as the future default once considered stable.

Back Service

Environment variables for the Back service (backend API).

VariableRequiredDescription
PLAY_URLYesPublic URL of the play/frontend service
MINIMUM_DISTANCENoMinimum distance (in pixels) before users are considered to be in proximity. Defaults to 64
GROUP_RADIUSNoRadius (in pixels) of a group/bubble. Defaults to 48
ADMIN_API_URLNoURL of the admin API for centralized configuration
ADMIN_API_TOKENNoAuthentication token for the admin API
CPU_OVERHEAT_THRESHOLDNoCPU usage threshold (in %) that triggers dropping intermediate movement packets to ease to CPU load. Defaults to 80
JITSI_URLNoURL of the Jitsi Meet server for video conferencing
JITSI_ISSNoJitsi JWT issuer for authentication
SECRET_JITSI_KEYNoSecret key for Jitsi JWT token generation
BBB_URLNoBigBlueButton server URL for video conferencing
BBB_SECRETNoBigBlueButton shared secret for API authentication
ENABLE_MAP_EDITORNoEnable the built-in map editor. Defaults to false
HTTP_PORTNoHTTP port for the back service. Defaults to 8080
GRPC_PORTNogRPC port for the back service. Defaults to 50051
MAX_PER_GROUPYesMaximum number of users in a bubble/group. Defaults to 4
REDIS_HOSTNoRedis server hostname or IP address
REDIS_PORTNoRedis server port. Defaults to 6379
REDIS_PASSWORDNoRedis authentication password
STORE_VARIABLES_FOR_LOCAL_MAPSNoIf true, store player variables even for local maps (not recommended for production). Defaults to false
PROMETHEUS_AUTHORIZATION_TOKENNoThe token to access the Prometheus metrics.
PROMETHEUS_PORTNoThe port to access the Prometheus metrics. If not set, the default port is used AND an authorization token is required.
MAP_STORAGE_URLNoThe URL to the gRPC endpoint of the map-storage server (for instance: "map-storage.example.com:50053")
PUBLIC_MAP_STORAGE_URLNoThe public URL to the map-storage server (for instance: "https://map-storage.example.com")
INTERNAL_MAP_STORAGE_URLNoThe internal URL to the map-storage server (for instance: "https://map-storage:3000")
PLAYER_VARIABLES_MAX_TTLNoThe maximum time to live of player variables for logged players, expressed in seconds (no limit by default). Use "-1" for infinity. Note that anonymous players don't have any TTL limit because their data is stored in local storage, not in Redis database.
ENABLE_CHATNoEnable/disable the chat feature. Defaults to true
ENABLE_CHAT_UPLOADNoEnable/disable file upload in chat. Defaults to true
ENABLE_TELEMETRYNoBy default, WorkAdventure will send telemetry usage once a day. This data contains the version of WorkAdventure used and very rough usage (max number of users...). The statistics collected through telemetry can provide developers valuable insights into WorkAdventure versions that are actually used. No personal user data is sent. Please keep this setting to true unless your WorkAdventure installation is 'secret'.
SECURITY_EMAILNoThis email address will be notified if your WorkAdventure version contains a known security flaw. ENABLE_TELEMETRY must be set to "true" for this.
TELEMETRY_URLNoURL where telemetry data is sent.
SENTRY_DSNNoIf set, WorkAdventure will send errors to Sentry
SENTRY_RELEASENoThe Sentry release we target. Only used if SENTRY_DSN is configured.
SENTRY_TRACES_SAMPLE_RATENoThe Sentry traces sample rate. Only used if SENTRY_DSN is configured. Defaults to 0.1
SENTRY_ENVIRONMENTNoThe Sentry environnement we target. Only used if SENTRY_DSN is configured.
GRPC_MAX_MESSAGE_SIZEYesThe maximum size of a gRPC message. Defaults to 20 MB.
LIVEKIT_HOSTNoThe Livekit host.
LIVEKIT_API_KEYNoThe Livekit API key.
LIVEKIT_API_SECRETNoThe Livekit API secret.
MAX_USERS_FOR_WEBRTCYesThe maximum number of users for WebRTC.
LIVEKIT_RECORDING_S3_ENDPOINTNoThe S3 endpoint for Livekit recording.
LIVEKIT_RECORDING_S3_ACCESS_KEYNoThe S3 access key for Livekit recording.
LIVEKIT_RECORDING_S3_SECRET_KEYNoThe S3 secret key for Livekit recording.
LIVEKIT_RECORDING_S3_REGIONNoThe S3 region for Livekit recording.
LIVEKIT_RECORDING_S3_BUCKETNoThe S3 bucket for Livekit recording.

Map Storage Service

Environment variables for the Map Storage service.

VariableRequiredDescription
API_URLYesThe URI(s) of the back server
AWS_ACCESS_KEY_IDNoAWS access key ID for S3 storage. If empty, local storage is used instead.
AWS_SECRET_ACCESS_KEYNoAWS secret access key for S3 storage. If empty, local storage is used instead.
AWS_DEFAULT_REGIONNoAWS region for S3 storage (e.g., 'us-east-1', 'eu-west-1')
AWS_BUCKETNoS3 bucket name for map storage. If empty, local storage is used instead.
AWS_URLNoURL of the S3 endpoint.
S3_MAX_PARALLEL_REQUESTSNoThe maximum parallel number of requests done to the S3 bucket. Defaults to 50.
S3_CONNECTION_TIMEOUTNoThe timeout in milliseconds for the S3 connection in milliseconds. Defaults to 5000 (5 seconds).
S3_REQUEST_TIMEOUTNoThe timeout in milliseconds for the S3 requests in milliseconds. Defaults to 60000 (60 seconds).
S3_UPLOAD_CONCURRENCY_LIMITNoMaximum number of concurrent S3 upload operations. Defaults to 100
MAX_UNCOMPRESSED_SIZENoThe maximum size of an uploaded file. This the total size of the uncompressed file (not the ZIP file). Defaults to 1GB
USE_DOMAIN_NAME_IN_PATHNoIf true, the domain name will be used as a top level directory when fetching/storing files
PATH_PREFIXNoThe prefix to strip if a reverse proxy is proxying calls to the map-storage from a path, e.g. /map-storage
STORAGE_DIRECTORYNoStorage directory for the maps on physical disk. Used if S3 storage is not configured.
CACHE_CONTROLNoThe cache-control HTTP header to be used for "normal" resources. Note: resources containing a hash in the name will be set to "immutable", whatever this setting is.
ENABLE_WEB_HOOKNoIf true, the webhook will be called when a WAM file is created
WEB_HOOK_URLNoThe URL of the webhook to call when a WAM file is created / updated / deleted. The URL will be called using POST.
WEB_HOOK_API_TOKENNoThe (optional) API token to use when calling the webhook. The token will be sent in the Authorization header of the POST request.
MAX_SIMULTANEOUS_FS_READSNoThe maximum number of simultaneous file system (local or S3) reads when regenerating the cache file. Defaults to 100.
SENTRY_DSNNoIf set, WorkAdventure will send errors to Sentry
SENTRY_RELEASENoThe Sentry release we target. Only used if SENTRY_DSN is configured.
SENTRY_ENVIRONMENTNoThe Sentry environment we target. Only used if SENTRY_DSN is configured.
SENTRY_TRACES_SAMPLE_RATENoThe sampling rate for Sentry traces. Only used if SENTRY_DSN is configured. Defaults to 0.1
AUTHENTICATION_STRATEGYNoDeprecated. Use ENABLE_BEARER_AUTHENTICATION, ENABLE_BASIC_AUTHENTICATION or ENABLE_DIGEST_AUTHENTICATION instead
ENABLE_BEARER_AUTHENTICATIONNoEnables bearer authentication. When true, you need to set either AUTHENTICATION_TOKEN or AUTHENTICATION_VALIDATOR_URL
AUTHENTICATION_TOKENNoThe hard-coded bearer token to use for authentication
AUTHENTICATION_VALIDATOR_URLNoThe URL that will be used to remotely validate a bearer token
ENABLE_BASIC_AUTHENTICATIONNoEnables basic authentication. When true, you need to set both AUTHENTICATION_USER and AUTHENTICATION_PASSWORD
ENABLE_DIGEST_AUTHENTICATIONNoEnables basic authentication. When true, you need to set both AUTHENTICATION_USER and AUTHENTICATION_PASSWORD
AUTHENTICATION_USERNoUsername for Basic or Digest authentication
AUTHENTICATION_PASSWORDNoPassword for Basic or Digest authentication
WAM_TEMPLATE_URLNoThe URL to fetch an empty WAM template
ENTITY_COLLECTION_URLSNoA comma separated list of entity collection URLs to be used when a new TMJ map is uploaded. Note: ignored if WAM_TEMPLATE_URL is set.
MAP_STORAGE_API_TOKENYesAPI token to access the map-storage REST API
PUSHER_URLYesURL of the pusher service
WHITELISTED_RESOURCE_URLSNoComma-separated list of allowed URLs for loading external resources
SECRET_KEYNoThe JWT token to use when the map-storage is used as a file server. This token will be used to authenticate the user when accessing files.
GRPC_MAX_MESSAGE_SIZEYesThe maximum size of a gRPC message. Defaults to 20 MB.
BODY_PARSER_JSON_SIZE_LIMITNoThe maximum size of JSON request bodies accepted by the body parser (used in PUT / PATCH HTTP requests). Defaults to 100mb. Examples: '50mb', '200mb', '1gb'

Deprecated Variables

The following variables are deprecated and will be removed in a future version. Please use the OPENID_* equivalents instead.

VariableRequiredDescription
OPID_CLIENT_IDNo-
OPID_CLIENT_SECRETNo-
OPID_CLIENT_ISSUERNo-
OPID_CLIENT_REDIRECT_URLNo-
OPID_CLIENT_REDIRECT_LOGOUT_URLNo-
OPID_PROFILE_SCREEN_PROVIDERNo-
OPID_SCOPENo-
OPID_PROMPTNo-
OPID_USERNAME_CLAIMNo-
OPID_LOCALE_CLAIMNo-
OPID_WOKA_NAME_POLICYNo-
OPID_TAGS_CLAIMNo-