Skip to content

README-Docker.md

Latest commit

 

History

History
261 lines (194 loc) · 7.09 KB

README-Docker.md

File metadata and controls

261 lines (194 loc) · 7.09 KB
Raw

ServiceRadar Docker Quick Start

This guide gets you started with ServiceRadar using Docker Compose in under 5 minutes.

Prerequisites

  • Docker Engine 20.10+ with Docker Compose 2.0+
  • 8GB+ RAM
  • 50GB+ disk space

OS-Specific Setup

AlmaLinux 9 / RHEL 9 / Rocky Linux 9

# Install Docker
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Enable and start Docker
sudo systemctl enable --now docker

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Git (if needed)
sudo dnf install -y git

Ubuntu / Debian

# Install Docker
curl -fsSL https://get.docker.com | sudo sh

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

macOS

Install Docker Desktop and ensure it's running.

Quick Start

  1. Clone and navigate:

    git clone https://github.com/carverauto/serviceradar.git
cd serviceradar

  2. Create environment file:

    cp .env.example .env

  3. Pull the images:

    docker compose pull

  4. Start ServiceRadar:

    docker compose up -d

By default, Compose pulls latest tags. Set APP_TAG when you need a pinned release or commit. To default to the dev compose overlay (no -f), set COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml in .env.

  1. Get your admin password:

    docker compose logs config-updater | grep "Password:"

  2. Access ServiceRadar:

Update an Existing Stack

  1. Optional: choose a target image tag (Compose defaults to latest):

    • Latest release: APP_TAG=v1.0.77
    • Specific commit: APP_TAG=sha-<git-sha>

  2. Pull + restart with the new tag:

    export APP_TAG=v1.0.77
docker compose pull
docker compose up -d --force-recreate

Startup Sequence

The stack automatically handles certificate generation and configuration:

  1. cert-generator - Creates all mTLS certificates (one-shot)
  2. cnpg - PostgreSQL with mTLS + password auth
  3. cert-permissions-fixer - Sets proper certificate ownership (one-shot)
  4. config-updater - Writes the bootstrap admin password (one-shot)
  5. nats - Message broker with mTLS
  6. datasvc - Internal coordination service (planned to be phased out)
  7. core-elx, agent-gateway, web-ng - Control plane services
  8. zen, log-promotion, db-event-writer - Bulk ingestion consumers
  9. agent - Edge agent (collectors + embedded engines + Wasm plugins)

Test Your Setup

Run the included test script:

./test-docker-setup.sh

CNPG mTLS Notes

The CNPG container enforces mTLS + password for all TCP connections. Client certs are generated by cert-generator and stored in the cert-data volume.

For existing installations, we now store CNPG credentials in the cnpg-credentials volume to avoid shipping static passwords. If you already have a data volume, you must seed the credentials once so services can connect. To seed them:

docker compose run --rm \
  -e CNPG_PASSWORD=<app-password> \
  -e CNPG_SUPERUSER_PASSWORD=<postgres-password> \
  -e CNPG_SPIRE_PASSWORD=<spire-password> \
  db-credentials

Example psql connection (from host):

APP_PASSWORD=$(docker compose exec -T cnpg cat /etc/serviceradar/cnpg/serviceradar-password)
PGSSLMODE=verify-full \
PGSSLROOTCERT=/path/to/root.pem \
PGSSLCERT=/path/to/workstation.pem \
PGSSLKEY=/path/to/workstation-key.pem \
PGPASSWORD="${APP_PASSWORD}" \
psql -h localhost -p 5455 -U serviceradar -d serviceradar

Device Enrichment Rule Overrides

core-elx supports filesystem override rules at /var/lib/serviceradar/rules/device-enrichment. By default Compose binds ./docker/compose/rules/device-enrichment into that path (read-only).

# Optional: use a custom host directory for overrides
export DEVICE_ENRICHMENT_RULES_DIR_HOST=/path/to/rules
docker compose up -d --force-recreate core-elx
docker compose logs core-elx | grep "Device enrichment rules loaded"

What's Next?

Build Images Locally (Bazel)

ServiceRadar container images are built with Bazel. Load the agent image into your local Docker daemon before starting Compose:

bazel run //docker/images:agent_image_amd64_tar

To publish the agent image (and the rest of the stack) to GHCR using the same Bazel targets:

# Push just the agent image
bazel run //docker/images:agent_image_amd64_push

# Or push every image in one go
bazel run //docker/images:push_all

Common Commands

# View all service status
docker compose ps

# View logs for all services
docker compose logs

# View logs for specific service
docker compose logs core-elx

# Follow logs in real-time
docker compose logs -f

# Stop all services
docker compose down

# Restart a service
docker compose restart core-elx

# Update to a specific version
export APP_TAG=v1.0.77
docker compose pull
docker compose up -d --force-recreate

Troubleshooting

If services fail to start:

  1. Check logs: docker compose logs [service-name]
  2. Verify resources: Ensure Docker has enough memory/CPU
  3. Check ports: Ensure ports 80, 8090, 514, 162 are available
  4. Reset: docker compose down && docker volume prune && docker compose up -d

AlmaLinux 9 / RHEL 9 Specific Issues

SELinux blocking containers:

# Allow containers to manage cgroups
sudo setsebool -P container_manage_cgroup on

# Or temporarily disable SELinux (not recommended for production)
sudo setenforce 0

Firewall blocking ports:

sudo firewall-cmd --add-port=80/tcp --permanent    # Web UI (Caddy)
sudo firewall-cmd --add-port=443/tcp --permanent   # Web UI HTTPS (optional)
sudo firewall-cmd --add-port=8090/tcp --permanent  # Core API (direct)
sudo firewall-cmd --reload

Certificate permission issues:

# Check cert-permissions-fixer ran successfully
docker compose logs cert-permissions-fixer

Security Notice

On first startup, ServiceRadar generates:

  • Random admin password
  • API keys and JWT secrets
  • mTLS certificates for all services

Save your admin password. The password is stored in the admin creds volume at /etc/serviceradar/admin/admin-password (mounted into web-ng and config-updater):

docker compose exec web-ng cat /etc/serviceradar/admin/admin-password

Support