Set Up the Drone CI Server and Agent (2026)

Drone’s agent is completely stateless, so you can run as many as you need to scale your build capacity.

Here’s a Drone server and agent running with Docker.

First, you’ll need a PostgreSQL database to store Drone’s metadata.

docker run \
  --name drone-db \
  -e POSTGRES_USER=drone \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=drone \
  -v drone_db:/var/lib/postgresql/data \
  postgres:13

Next, the Drone server itself. We’re using a self-signed certificate here for simplicity, but you’ll want to use a proper certificate in production.

docker run \
  --name drone-server \
  -p 80:80 \
  -p 443:443 \
  -e DRONE_GITHUB=true \
  -e DRONE_GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID \
  -e DRONE_GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET \
  -e DRONE_RPC_SECRET=YOUR_RPC_SECRET \
  -e DRONE_DATABASE_DRIVER=postgres \
  -e DRONE_DATABASE_DATASOURCE="postgres://drone:secret@host.docker.internal:5432/drone?sslmode=disable" \
  -v drone_server:/var/lib/drone/ \
  drone/drone:1

Replace YOUR_GITHUB_CLIENT_ID and YOUR_GITHUB_CLIENT_SECRET with your GitHub OAuth application credentials. You can create one at https://github.com/settings/applications/new. Set the Authorization callback URL to http://your.drone.domain/login/github.

host.docker.internal assumes you’re running the Docker daemon on your local machine. If Drone is running in a different environment (e.g., a cloud VM), you’ll need to replace this with the actual IP address or hostname of your PostgreSQL instance.

Now, the Drone agent. This is where your builds actually run.

docker run \
  --name drone-agent \
  -e DRONE_SERVER=http://your.drone.domain \
  -e DRONE_RPC_SECRET=YOUR_RPC_SECRET \
  -v /var/run/docker.sock:/var/run/docker.sock \
  drone/agent:1

Make sure http://your.drone.domain points to your Drone server. The agent needs to communicate with the server to get build jobs.

The DRONE_RPC_SECRET must match the one set for the Drone server. This is how the agent authenticates with the server.

The agent mounts the Docker socket (/var/run/docker.sock) so it can create and manage Docker containers for your builds.

With this setup, when a build is triggered, the Drone server will assign the job to an available agent. The agent will then pull the specified Docker image, clone your repository, and execute the build steps defined in your .drone.yml file.

The magic of the stateless agent is that you can run multiple instances of this agent command. Drone will automatically distribute build jobs across all connected agents. If an agent crashes, Drone will simply reassign its current jobs to other available agents.

The DRONE_DATABASE_DATASOURCE format is driver://username:password@host:port/database?sslmode=disable. The sslmode=disable is for local development; in production, you’ll want to configure SSL for your PostgreSQL connection.

The DRONE_SERVER environment variable for the agent is crucial. It tells the agent where to find the central Drone server to receive build instructions. If this is incorrect, the agent will simply sit idle, unable to connect.

If you encounter issues, check the logs of both the drone-server and drone-agent containers using docker logs <container_name>. Common problems include incorrect DRONE_RPC_SECRET, network connectivity issues between the agent and server, or problems with the PostgreSQL connection.

The next step is to configure your .drone.yml file to define your build pipelines.