Docker deployment

This is the quickest way to get an agent running. Everything lands on one host, which makes it a good fit for evaluation and for small production deployments where you do not already run Kubernetes.

For what you are deploying and why, see Deploying the agent.

Before you start

• Docker Engine with the Compose plugin. Run docker compose version to confirm.
• Your `config.yml`, downloaded from the platform in step 2 of registration.
• Your authentication key, from step 3, already pasted into that file.
• Network access as described in Network access.

Step 1: Create a directory

Everything lives in one folder. Put the configuration file the platform gave you next to the compose file:

mkdir vaurd-agent && cd vaurd-agent
# copy the downloaded config.yml into this directory

Step 2: Adjust the configuration for containers

The file the platform generates is set up for a single machine. Three settings need to point at container names instead of localhost, so the components can find each other on the Compose network:

services:
  storage:
    # Must be the shared volume mount path, not "."
    data_dir: /data

  nats:
    # "nats" is the service name in the compose file below
    endpoint: nats://nats:4222
    username: natsuser
    password: natspassword

  core:
    # "core" is the service name in the compose file below
    address: core:5001
    server_name: vaurd-agent

Leave everything else the platform generated as it is, including the certificates and your license key.

This is also where you add your data sources. Each entry's name must exactly match the technical name of the source you created in the platform:

sources:
  - name: orders_db
    type: database_postgres
    params:
      host: db.internal
      port: 5432
      user: vaurd
      password: <password>
      database: orders

Every setting in the file is documented in Agent configuration.

Step 3: Create the compose file

Save this as docker-compose.yml in the same directory:

services:
  nats:
    image: nats:latest
    command: "-js --user natsuser --pass natspassword"
    ports: ["4222:4222", "8222:8222"]

  core:
    image: vaurd/vaurd-agent-core:v0.1.0
    ports: ["5001:5001"]
    volumes:
      - agent-data:/data
      - ./config.yml:/etc/vaurd/config.yml:ro
    depends_on: [nats]

  ingestion:
    image: vaurd/vaurd-agent-ingestion:v0.1.0
    ports: ["5002:5002"]
    volumes:
      - agent-data:/data
      - ./config.yml:/etc/vaurd/config.yml:ro
    depends_on: [nats]

  worker:
    image: vaurd/vaurd-agent-worker:v0.1.0
    volumes:
      - agent-data:/data
      - ./config.yml:/etc/vaurd/config.yml:ro
    depends_on: [nats, core]

volumes:
  agent-data: # shared across all three components

Three things about this file are worth understanding rather than just copying.

The `agent-data` volume is shared by all three components. They open the same /data/vaurd.db and read the same plugin binaries from /data/plugins. This is not three separate caches; it is one database with three readers and writers. Do not give each component its own volume.

The same `config.yml` is mounted into all three containers at /etc/vaurd/config.yml, read-only. Every process reads its settings from this one file, and environment variables are ignored.

The NATS password in the compose command must match the one in `config.yml`. The --user and --pass flags start the server with those credentials, and services.nats in your config connects with them. Change one and you must change the other.

The worker service publishes no ports. It takes flows off the queue and connects out to your sources, so nothing needs to reach it.

Step 4: Start the agent

docker compose up -d

Check that everything came up:

docker compose ps
docker compose logs -f core

Core should report that it is listening on port 5001. Ingestion and worker may restart once or twice while they wait for core; that settles by itself.

Step 5: Confirm the agent is answering

Ingestion answers over HTTP:

curl http://localhost:5002/api/v1/healthcheck

Core answers the standard gRPC health check. Check it with grpcurl, run from the directory holding your config.yml so yq can read the CA certificate out of it:

grpcurl -cacert <(yq -r '.ca_cert' config.yml) localhost:5001 grpc.health.v1.Health/Check

{
  "status": "SERVING"
}

Run that same command from outside the host, against the endpoint you gave the agent, to confirm Vaurd will be able to reach it too. Core also enables gRPC reflection, so swapping grpc.health.v1.Health/Check for list shows you everything it exposes.

At this point the containers are running but the agent is not registered yet, so it will not process anything. Go back to step 5 of registration and start registration from the web application.

Once registration completes, core downloads the plugins for your configured source types into the shared volume, and the agent moves to Connected.

Keeping it running

The compose file above has no restart policy, so nothing comes back after a reboot or a crash. For anything beyond a trial, add one to each of the four services:

    restart: unless-stopped

Pin your image tags too. The example uses v0.1.0 rather than latest so that a redeploy gives you the same build you tested.

Updating configuration

Edit config.yml, then restart the components so they pick it up:

docker compose restart core ingestion worker

This is how you add or change a data source. See Updating your sources.

Upgrading the agent

Change the image tags in docker-compose.yml, then:

docker compose pull
docker compose up -d

The agent-data volume is not touched, so the agent keeps its identity, its registration and its history.

Stopping and removing

docker compose down            # stops the containers, keeps the data
docker compose down -v         # also deletes the shared volume

Removing the volume deletes the agent's database. It will need to be registered again.

Troubleshooting

Ingestion or worker restart in a loop. They cannot reach core. Check docker compose logs core for a registration failure. A wrong license key or an unreachable platform address shows up there.

Core never becomes ready. It cannot reach the Vaurd platform. Check vaurd.manager_url and the CA certificate block in your config, and confirm the host has outbound access.

Registration fails from the web application. The platform cannot reach the agent. Port 5001 has to be reachable from Vaurd at the endpoint you entered when creating the agent. Check it from outside the host with grpcurl -cacert <(yq -r '.ca_cert' config.yml) <your-agent-endpoint>:5001 grpc.health.v1.Health/Check, which should return SERVING.

Configuration changes have no effect. The agent only reads /etc/vaurd/config.yml. Confirm the bind mount path is right, and restart the containers after editing.