Skip to main content

Set Up Environment Variables

The BuildNinja Server and Agent rely on environment variables to define their configuration and communication parameters. These variables determine how the server manages builds, connects to the database, and handles authentication, as well as how the agent registers itself, communicates with the server, and stores local data.

If you install the server and agent using the installers, the essential environment variables are automatically configured. You only need to set additional variables if you wish to customize or extend the server and agent behavior according to your deployment requirements.

The following is a list of required and optional environment variables.

VariableDescriptionWindows ExampleLinux ExampleCategoryApplies ToConfigured by Installer
BN_SERVER_PUBLIC_URLBase URL used in communication between the server and agents.http://localhost:8800http://localhost:8800RequiredServer❌
BN_SERVER_MONGOURIMongoDB connection URI used by the BuildNinja server to connect to a MongoDB instance.mongodb://user:pass@localhost:27017/xxcicd_db?authSource=adminmongodb://user:pass@localhost:27017/xxcicd_db?authSource=adminRequiredServer✅
BN_SERVER_MONGODBName of the MongoDB database that BuildNinja connects to.bn_server_stagebn_server_stageRequiredServer✅
BN_SERVER_JWT_SIGN_KEYSecret key used by BuildNinja to sign JWT tokens, ensuring they are trusted and verifiable.s3cure$ecretKey_123!xyzs3cure$ecretKey_123!xyzRequiredServer✅
BN_SERVER_PORTPort number the BuildNinja server binds to (default: 8800).88008800OptionalServer✅
BN_SERVER_DATA_DIRDirectory where BuildNinja stores internal data (temp files, assets, etc.). Default: {user_home}/bnserver/dataC:\BuildNinja\data/var/lib/buildninja/dataOptionalServer✅
BN_SERVER_SSL_CERTFile path to the server’s SSL/TLS certificate for HTTPS connections.C:\certs\buildninja.crt/etc/ssl/certs/buildninja.crtOptionalServer❌
BN_SERVER_SSL_KEYFile path to the server’s SSL/TLS private key for HTTPS connections.C:\certs\buildninja.key/etc/ssl/private/buildninja.keyOptionalServer❌
BN_AGENT_NAMEUnique identifier for the BuildNinja agent. The server uses this name to register, manage, and distinguish agents.agent-windows-01agent-linux-01RequiredAgent✅
BN_AGENT_PORTPort on which the BuildNinja agent listens for internal communication and reporting (default: 9500).95009500RequiredAgent✅
BN_AGENT_SERVER_URLURL of the BuildNinja server the agent connects to for registration, job assignments, and reporting.http://192.168.1.100:8800http://192.168.1.100:8800RequiredAgent✅
BN_AGENT_SELFURLPublicly accessible URL of the BuildNinja agent. Must be reachable by the server for job scheduling and communication.http://192.168.1.51:9500http://192.168.1.52:9500RequiredAgent✅
BN_AGENT_DATA_DIRLocal path where the agent stores runtime data (e.g., temp files, artifacts, logs, cached dependencies). Default: {user_home}/bnagent/dataC:\BuildNinja\agent\data/var/lib/buildninja/agent/dataOptionalAgent✅
note

When using the installers, all variables marked with ✅ are automatically configured during setup. You can modify or extend these variables later to customize your environment.

Next Steps​