Configure and Deploy with Docker

Docker provides an efficient and consistent way to deploy the BuildNinja Server and Agent using prebuilt Docker images. Running BuildNinja in containers simplifies setup, ensures environment consistency, and makes it easier to manage deployments across multiple systems.

Prepare Project Structure

Organize the project directory using the following recommended structure:

project/
└── docker-compose.yml

Deploy Server and Agent Images

1. Create a docker-compose.yml file.

   docker-compose.yml

   version: '3.8'
   
   services:
     # Server service definition.
     server:
       image: grapehub/buildninja-server:tagName  # Use the BuildNinja server image with the specified tag.
       ports:
         - "8800:8800"  # Map host port 8800 to container port 8800.
       environment:
         - BN_SERVER_PORT=8800  # Port the server listens on.
         - BN_SERVER_MONGOURI=mongodb://host.docker.internal:27017  # MongoDB connection URI (host machine).
         - BN_SERVER_MONGODB=bn_server_stage  # Name of the MongoDB database.
   
     # Agent service definition
     agent:
       image: grapehub/buildninja-agent:tagName  # Use the BuildNinja agent image with the specified tag.
       ports:
         - "9500:9500"  # Map host port 9500 to container port 9500.
       environment:
         - BN_AGENT_NAME=agent-linux-01  # Identifier for this agent.
         - BN_AGENT_PORT=9500  # Port the agent listens on.
         - BN_AGENT_SERVER_URL=http(s)://<your-server-machine-ip>:8800  # Server endpoint the agent connects to.
         - BN_AGENT_SELFURL=http(s)://<your-agent-machine-ip>:9500  # Public URL used by the server to reach the agent.
   info

   For more information on environment variables, see Set Up Environment Variables.

2. Run the containers in detached mode.

   docker-compose up -d

note

Mapping a persistent host volume to the container’s BN_SERVER_DATA_DIR ensures that the server retains generated assets across restarts. Since container filesystems are ephemeral by default, any runtime data not stored in a mapped volume will be lost when the container restarts.

Access BuildNinja Web Interface

1. Open a browser and visit http://<your-server-ip>:8800/.

   

2. Use the default administrator credentials to sign in:

   • Email: root
   • Password: root@123

   

3. Click Sign in to continue.

   

4. After signing in, the "Sign-in" page will prompt you to reset the password. Enter the following details:

   • Current Password: The default administrator password.
   • New Password: Enter a strong password for your account, at least 8 characters with a combination of letters, numbers, and special characters.
   • Confirm New Password: Enter the password you have entered in the "New Password" field.

   

5. Click Update Password to reset the password.

   After successfully resetting your password, BuildNinja will automatically redirect you to the Dashboard .

Verify Agent Registration

The agent attempts to register itself with the server using the provided details. If the registration is successful, the server UI displays the agent in the Agents section.

info

For instructions on authorizing the agent, see Authorize Agent.