|
| 1 | +--- |
| 2 | +menutitle: Docker |
| 3 | +title: Docker deployment |
| 4 | +draft: false |
| 5 | +weight: 50 |
| 6 | +date: 2026-06-21 |
| 7 | +last_reviewed: 2026-06-23 |
| 8 | +summary: | |
| 9 | + Run the Velociraptor server inside a Docker container, using the |
| 10 | + officially supported image from the GitHub Container Registry. |
| 11 | +description: | |
| 12 | + Run the Velociraptor server inside a Docker container, using the |
| 13 | + officially supported image from the GitHub Container Registry. |
| 14 | +--- |
| 15 | + |
| 16 | +From [Velociraptor 0.77](/blog/2026/2026-05-31-release-notes-0.77/), |
| 17 | +an officially supported Docker container is available from the |
| 18 | +[GitHub Container Registry](https://ghcr.io/velocidex/velociraptor-server). |
| 19 | +You can use it to run the Velociraptor server in a containerized |
| 20 | +environment without needing to install packages or manage binaries |
| 21 | +directly. |
| 22 | + |
| 23 | +The source files for the container (including the `Dockerfile`, |
| 24 | +`compose.yaml`, entrypoint script, and configuration VQL) live in the |
| 25 | +main Velociraptor repository under the |
| 26 | +[`Docker/`](https://github.com/Velocidex/velociraptor/tree/master/Docker) |
| 27 | +directory. That directory's |
| 28 | +[README](https://github.com/Velocidex/velociraptor/blob/master/Docker/README.md) |
| 29 | +contains the full technical reference and step-by-step instructions. |
| 30 | + |
| 31 | +The CI system builds the container image automatically and publishes |
| 32 | +it whenever changes are merged to the main branch. The |
| 33 | +`ghcr.io/velocidex/velociraptor-server:latest` tag always points to |
| 34 | +the most recent build. Release versions are tagged with their version |
| 35 | +number (for example, `ghcr.io/velocidex/velociraptor-server:0.77`). |
| 36 | + |
| 37 | +You will need: |
| 38 | + |
| 39 | +- Docker (or a compatible container runtime, such as Podman) |
| 40 | +- `docker-compose` (or `docker compose`) |
| 41 | + |
| 42 | +## Deployment scenarios |
| 43 | + |
| 44 | +The container supports two main scenarios depending on whether you |
| 45 | +already have a Velociraptor deployment. |
| 46 | + |
| 47 | +### Fresh deployment |
| 48 | + |
| 49 | +If you don't have an existing Velociraptor server, the container can |
| 50 | +create everything from scratch: |
| 51 | + |
| 52 | +1. Copy the |
| 53 | + [`compose.yaml`](https://github.com/Velocidex/velociraptor/blob/master/Docker/compose.yaml) |
| 54 | + and |
| 55 | + [`.env`](https://github.com/Velocidex/velociraptor/blob/master/Docker/.env) |
| 56 | + files from the repository's `Docker/` directory into a new project |
| 57 | + directory. |
| 58 | +2. Adjust the `.env` file if needed (hostname, ports, admin password). |
| 59 | +3. Run `docker-compose up`. |
| 60 | + |
| 61 | +On first startup, the container: |
| 62 | + |
| 63 | +- Generates a new configuration file with self-signed certificates |
| 64 | +- Creates an initial `admin` user with the password from the `.env` |
| 65 | + file (default: `password`) |
| 66 | +- Starts the Velociraptor frontend on the configured ports |
| 67 | +- Builds client deployment packages (MSI, DEB, RPM) |
| 68 | + |
| 69 | +The container stores the generated configuration file in the `etc/` |
| 70 | +directory and keeps the datastore in the `datastore/` directory. Both |
| 71 | +directories are mounted as volumes, so data persists across |
| 72 | +container restarts. |
| 73 | + |
| 74 | +You can connect to the GUI at `https://localhost:8889/` (or the host |
| 75 | +and port you configured). |
| 76 | + |
| 77 | +### Existing deployment with your own configuration |
| 78 | + |
| 79 | +If you already have a Velociraptor deployment, you can point the |
| 80 | +container at your existing configuration file: |
| 81 | + |
| 82 | +1. Place your existing `server.config.yaml` in the `etc/` directory. |
| 83 | +2. Ensure your `.env` file reflects your server's hostname and ports. |
| 84 | +3. Run `docker-compose up`. |
| 85 | + |
| 86 | +The container detects the existing configuration file and skips the |
| 87 | +generation step, starting the frontend directly. The datastore volume |
| 88 | +gives the container access to your existing data. |
| 89 | + |
| 90 | +## Upgrading |
| 91 | + |
| 92 | +Upgrading a Docker-based deployment is straightforward because all |
| 93 | +persistent data is stored on mounted volumes. |
| 94 | + |
| 95 | +{{% notice info "Keep your configuration file" %}} |
| 96 | + |
| 97 | +Your configuration file contains the cryptographic keys that establish |
| 98 | +trust between the server and its clients. When upgrading, you must |
| 99 | +reuse the same configuration file so that existing clients can |
| 100 | +continue to communicate with the server. |
| 101 | + |
| 102 | +Before upgrading, make a backup copy of your configuration file |
| 103 | +(located in the `etc/` directory). Keep it somewhere safe. |
| 104 | + |
| 105 | +{{% /notice %}} |
| 106 | + |
| 107 | +To upgrade: |
| 108 | + |
| 109 | +1. Pull the latest image: |
| 110 | + ```bash |
| 111 | + docker pull ghcr.io/velocidex/velociraptor-server:latest |
| 112 | + ``` |
| 113 | +2. Stop the running container: |
| 114 | + ```bash |
| 115 | + docker-compose down |
| 116 | + ``` |
| 117 | +3. Start again with the new image: |
| 118 | + ```bash |
| 119 | + docker-compose up |
| 120 | + ``` |
| 121 | + |
| 122 | +The new container runs the latest Velociraptor binary using your |
| 123 | +existing configuration file and datastore. Clients reconnect using |
| 124 | +the same cryptographic keys and continue operating normally. |
| 125 | + |
| 126 | +If you want to pin a specific version, change the image tag in your |
| 127 | +`compose.yaml` from `:latest` to a version tag such as |
| 128 | +`ghcr.io/velocidex/velociraptor-server:0.77`. |
| 129 | + |
| 130 | +## Environment variables |
| 131 | + |
| 132 | +The following environment variables (set in the `.env` file or passed |
| 133 | +directly to the container) control the container's behavior: |
| 134 | + |
| 135 | +| Variable | Default | Description | |
| 136 | +|---|---|---| |
| 137 | +| `VELOCIRAPTOR_HOSTNAME` | `localhost` | Public hostname or IP that clients use to reach the server | |
| 138 | +| `VELOCIRAPTOR_FRONTEND_PORT` | `8000` | Port for client communication | |
| 139 | +| `VELOCIRAPTOR_GUI_PORT` | `8889` | Port for the web GUI | |
| 140 | +| `VELOCIRAPTOR_DATASTORE_PATH` | `/datastore/` | Path inside the container where the datastore is stored | |
| 141 | +| `VELOCIRAPTOR_CONFIG_PATH` | `/etc/velociraptor/server.config.yaml` | Path inside the container for the server config file | |
| 142 | +| `VELOCIRAPTOR_INITIAL_ADMIN_PASSWORD` | `password` | Initial password for the admin user | |
| 143 | +| `VELOCIRAPTOR_NO_INITIALIZE` | _(not set)_ | Set to `TRUE` to skip building MSI/DEB/RPM packages on first start | |
| 144 | +| `VELOCIRAPTOR_LITERAL_CONFIG` | _(not set)_ | If set, uses the value as the literal config instead of reading from a file | |
| 145 | + |
| 146 | +## Customization |
| 147 | + |
| 148 | +You can customize the server's behavior by providing your own |
| 149 | +artifacts. The container loads artifacts from the |
| 150 | +`/custom_artifacts/` directory inside the container. The |
| 151 | +`InitializeServer.yaml` artifact (which runs on first startup to |
| 152 | +build client packages) lives there by default. You can override it |
| 153 | +by mounting your own directory of custom artifacts over |
| 154 | +`/custom_artifacts/`. |
| 155 | + |
| 156 | +See the |
| 157 | +[`Docker/`](https://github.com/Velocidex/velociraptor/tree/master/Docker) |
| 158 | +directory in the main Velociraptor repository for details about the |
| 159 | +entrypoint, initialization VQL, and customization options. |
0 commit comments