GitHub Repository: github.com/Xboarder56/velociraptor-docker

Velociraptor (Server) in Docker

Run the Velocidex Velociraptor server in a container with sensible defaults, HTTPS, and prebuilt client repacks.

• Architectures: linux/amd64, linux/arm64
• Ports: 8000 (client/ingest), 8889 (GUI), 8001 (gRPC API), 8003 (Prometheus)
• Data dir: mount /velociraptor to persist config, keys, artifacts, and repacked clients
• TLS: self-signed cert generated on first run (you can rotate later)

On start, the container prints a small build banner (version, arch, base image, git commit, build date) so you can confirm what you pulled.

Quick Start

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

Open https://localhost:8889 (accept the self-signed cert) and log in with the bootstrap credentials below (you should change them right away).

Runtime Configuration (Environment Variables)

These variables are read at container start—no image rebuilds needed.

Persistent paths (mount a volume):

• /velociraptor/server.config.yaml — server config (auto-generated)
• /velociraptor/client.config.yaml — client config
• /velociraptor/client_bundles/ — repacked client binaries (.deb/.rpm/.exe/.msi)

Common Run Examples

1) Run quietly (INFO mode)

This overrides the default, which is to run with verbose (DEBUG) logs.

docker run -it --rm \
  -p 8000:8000 -p 8889:8889 -p 8001:8001 -p 8003:8003 \
  -v $PWD/velodata:/velociraptor \
  -e VELOX_DEFAULT_USER=admin -e VELOX_DEFAULT_PASSWORD='S3cure!' \
  -e VELOX_START_SERVER_VERBOSE=false \
  xboarder56/velociraptor:latest

2) Set the public URL clients should use

docker run -it --rm \
  -e VELOX_FRONTEND_HOSTNAME=velociraptor.example.com \
  -e VELOX_FRONTEND_PORT=443 \
  -e VELOX_FRONTEND_SERVER_SCHEME=https \
  -p 443:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

3) Use different public URLs for Client and GUI

docker run -it --rm \
  -e VELOX_FRONTEND_SERVER_URL=https://ingest.example.com:8000/ \
  -e VELOX_GUI_URL=https://admin.example.com:8889/ \
  -p 8000:8000 -p 8889:8889 \
  -v $PWD/velodata:/velociraptor \
  xboarder56/velociraptor:latest

Docker Compose

services:
  velociraptor:
    image: xboarder56/velociraptor:latest
    restart: unless-stopped
    environment:
      VELOX_DEFAULT_USER: admin
      VELOX_DEFAULT_PASSWORD: "S3cure!"
      VELOX_FRONTEND_HOSTNAME: velociraptor.example.com
      VELOX_START_SERVER_VERBOSE: "false"
    ports:
      - "8000:8000"   # client/ingest
      - "8889:8889"   # GUI
      - "8001:8001"   # gRPC API
      - "8003:8003"   # Metrics
    volumes:
      - ./velodata:/velociraptor

What to Expect on First Run

• The entrypoint generates a secure server.config.yaml and a client.config.yaml.
• Clients for Linux (amd64 + arm64), macOS (amd64 + arm64), and Windows (exe + msi) are repacked into /velociraptor/client_bundles/ with your server URL.
• You’ll see logs like:
  • GUI is ready to handle TLS requests on https://localhost:8889/
  • Frontend is ready to handle client TLS requests at https://localhost:8000/

Client Binaries

After startup, check ./velodata/client_bundles/ for repacked binaries:

• Linux: .deb and .rpm packages for amd64 and arm64
• macOS: repacked executables for amd64 and arm64
• Windows: .exe and .msi

If a specific upstream client binary isn’t available, the repack step is skipped (you’ll see a log message).

Security Notes

• Change the default credentials via VELOX_USER / VELOX_PASSWORD on first run.
• TLS is self-signed by default; rotate keys/certificates as needed from the server.
• Expose GUI/API only where appropriate; consider a reverse proxy or firewall rules.

Troubleshooting

• Seeing [DEBUG] FlowStorageManager housekeeping run?
  You likely set VELOX_START_SERVER_VERBOSE=true (adds -v). Remove it to suppress DEBUG.
• Ports already in use? Map them as needed: -p 443:8000 and set VELOX_FRONTEND_PORT=443.

Tags

• :latest — most recent successful build
• :<velociraptor-version> — e.g. :0.76.5. Floats to the latest re-release for that upstream patch.
• :<minor> — e.g. :0.76. Floats across patch releases within that minor.
• :sha-<short> — e.g. :sha-abc1234. Commit-pinned reproducible reference.
• Multi-arch manifests are published for amd64 and arm64

Build & Release Flow

This repo uses two GitHub Actions workflows:

• upstream-check.yml runs daily. It polls the Velocidex release feed and, if it sees a newer release or if upstream re-published binaries for the current version (with new sha256s), opens a PR bumping versions.env + binaries.lock. For platforms upstream hasn't published yet for the latest release, the workflow walks back through prior releases and pins those assets to the most recent release that does include them.
• build-publish.yml runs on tag pushes matching v* and on manual dispatch. It:
  1. Builds an amd64 image and runs scripts/ci-image-validation.sh against it (server starts, GUI responds, a repacked Linux client makes contact).
  2. Only if validation passes, does a multi-arch (linux/amd64, linux/arm64) buildx build and pushes to Docker Hub with provenance + SBOM attestations.

To cut a release:

1. Review and merge the PR from upstream-check.

2. Tag the merge commit with the value of VELOX_VERSION from versions.env (optionally suffixed with -<IMAGE_REVISION> when IMAGE_REVISION > 1):

   git tag v0.76.8        # first revision
   # or
   git tag v0.76.8-2      # subsequent re-release of the same upstream version
   git push --tags
   

3. Required Docker Hub secrets on the repo: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.

About This Fork

This repository is a fork of weslambert/velociraptor-docker, originally created by Wes Lambert.
It aims to maintain compatibility with the latest Velocidex Velociraptor releases while providing additional configuration options and deployment improvements for Docker environments.

All credit for the foundational work goes to Wes Lambert — this fork primarily adds quality-of-life enhancements, updated configurations, and maintenance updates.

Maintained by: Xboarder56
Upstream project: Velocidex Velociraptor