https://github.com/carverauto/serviceradar
Zero-trust Opensource Network Management and Observability Platform
https://github.com/carverauto/serviceradar
armis causal-discovery causal-inference deck-gl erts homelab monitoring-tool netbox network-monitoring-tool network-scanning observability ocsf ocsf-schema otel ubiquiti wasi wasm wazero zero-trust
Last synced: 2 months ago
JSON representation
Zero-trust Opensource Network Management and Observability Platform
- Host: GitHub
- URL: https://github.com/carverauto/serviceradar
- Owner: carverauto
- License: apache-2.0
- Created: 2025-01-13T18:33:55.000Z (over 1 year ago)
- Default Branch: staging
- Last Pushed: 2026-03-28T18:00:13.000Z (3 months ago)
- Last Synced: 2026-03-28T19:23:06.146Z (3 months ago)
- Topics: armis, causal-discovery, causal-inference, deck-gl, erts, homelab, monitoring-tool, netbox, network-monitoring-tool, network-scanning, observability, ocsf, ocsf-schema, otel, ubiquiti, wasi, wasm, wazero, zero-trust
- Language: JavaScript
- Homepage: http://docs.serviceradar.cloud/
- Size: 323 MB
- Stars: 848
- Watchers: 7
- Forks: 63
- Open Issues: 205
-
Metadata Files:
- Readme: README-Docker.md
- Changelog: CHANGELOG
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Governance: GOVERNANCE.md
- Roadmap: ROADMAP.md
- Maintainers: MAINTAINERS.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-unifi - carverauto/serviceradar - Zero-trust open-source network management and observability platform with UniFi support. (Monitoring & Metrics / Other Monitoring)
README
# 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
```bash
# 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
```bash
# 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](https://www.docker.com/products/docker-desktop/) and ensure it's running.
## Quick Start
1. **Clone and navigate**:
```bash
git clone https://github.com/carverauto/serviceradar.git
cd serviceradar
```
2. **Create environment file**:
```bash
cp .env.example .env
```
3. **Pull the images**:
```bash
docker compose pull
```
4. **Start ServiceRadar**:
```bash
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`.
5. **Get your admin password**:
```bash
docker compose logs config-updater | grep "Password:"
```
6. **Access ServiceRadar**:
- Web Interface: https://localhost (Caddy on port 443, self-signed)
- HTTP fallback: http://localhost (Caddy on port 80)
- API via Caddy: https://localhost/api/
- Email: `root@localhost`
- Password: (from step 5)
## 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-`
2. Pull + restart with the new tag:
```bash
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:
```bash
./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.
Docker Compose now auto-migrates an existing local PG16 `cnpg-data` volume to
PG18 during startup. For existing installs, the normal operator path is:
```bash
git pull
docker compose pull
docker compose up -d
```
Fresh installs and already-migrated PG18 volumes automatically no-op in the
migration step and continue startup normally.
The standalone migration helper remains available for explicit/manual recovery:
```bash
./docker/compose/migrate-cnpg-pg16-to-pg18.sh
```
If the old install used non-default credentials without a persisted
`cnpg-credentials` volume, provide them when running the standalone migration:
```bash
CNPG_SUPERUSER= \
CNPG_SUPERUSER_PASSWORD= \
CNPG_PASSWORD= \
./docker/compose/migrate-cnpg-pg16-to-pg18.sh
```
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 from the pre-security Docker Compose stack, the bootstrap
container will automatically recover the legacy defaults on first restart.
If you previously used the secure credential volume and lost it, or if you use
custom passwords, seed the credentials once so services can reconnect:
```bash
docker compose run --rm \
-e CNPG_SUPERUSER= \
-e CNPG_PASSWORD= \
-e CNPG_SUPERUSER_PASSWORD= \
db-credentials
```
Example psql connection (from host):
```bash
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).
```bash
# 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?
- **Configure devices**: See [Device Configuration Guide](docs/docs/device-configuration.md)
- **Full documentation**: See [Docker Setup Guide](docs/docs/docker-setup.md)
- **Security**: See [TLS Security Guide](docs/docs/tls-security.md) - Change your admin password after first login
## Build Images Locally (Bazel)
ServiceRadar container images are built with Bazel. Load the agent image into your local Docker daemon before starting Compose:
```bash
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:
```bash
# 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
```bash
# 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**:
```bash
# 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**:
```bash
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**:
```bash
# 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,
separate from the shared cert volume, at `/etc/serviceradar/admin/admin-password`:
```bash
docker compose exec web-ng cat /etc/serviceradar/admin/admin-password
```
## Support
- [Complete Documentation](docs/docs/)
- [Report Issues](https://github.com/carverauto/serviceradar/issues)
- [Community Support](https://github.com/carverauto/serviceradar/discussions)