Deploy Netdata with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it ideal for running Netdata alongside your other services.

This guide walks you through deploying Netdata with full host monitoring capabilities. Netdata requires access to host system metrics (CPU, memory, disk, network) through read-only mounts of /proc, /sys, and other system paths.

Prerequisites

• A VPS with at least 1 vCPU, 1 GB RAM, and 5 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., monitor.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  netdata:
    image: netdata/netdata:stable
    restart: unless-stopped
    ports:
      - "19999:19999"
    pid: host
    cap_add:
      - SYS_PTRACE
      - SYS_ADMIN
    security_opt:
      - apparmor:unconfined
    environment:
      - DO_NOT_TRACK=${DO_NOT_TRACK:-1}
      - NETDATA_CLAIM_TOKEN=${NETDATA_CLAIM_TOKEN:-}
      - NETDATA_CLAIM_URL=${NETDATA_CLAIM_URL:-https://app.netdata.cloud}
      - NETDATA_CLAIM_ROOMS=${NETDATA_CLAIM_ROOMS:-}
    volumes:
      - ../files/netdata-config:/etc/netdata
      - ../files/netdata-lib:/var/lib/netdata
      - ../files/netdata-cache:/var/cache/netdata
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
      - /etc/os-release:/host/etc/os-release:ro
      - /etc/passwd:/host/etc/passwd:ro
      - /etc/group:/host/etc/group:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:19999/api/v1/info || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: Netdata requires elevated privileges (SYS_PTRACE, SYS_ADMIN) and read-only access to host paths (/proc, /sys) for full system monitoring. The Docker socket mount enables container monitoring. All host mounts are read-only.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
DO_NOT_TRACK	Disable anonymous telemetry	1
NETDATA_CLAIM_TOKEN	Token to connect to Netdata Cloud (optional)	your-claim-token
NETDATA_CLAIM_URL	Netdata Cloud URL (optional)	https://app.netdata.cloud
NETDATA_CLAIM_ROOMS	Netdata Cloud room IDs (optional)	room-id-here

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Netdata Cloud integration is optional — Netdata works fully standalone with its local dashboard.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/netdata-config — Netdata configuration files (health alerts, collectors, streaming)
• ../files/netdata-lib — Persistent data storage (metrics database)
• ../files/netdata-cache — Cached metrics data for faster dashboard loading

Additionally, several read-only host mounts provide system metrics:

• /proc, /sys — Kernel metrics (CPU, memory, disk, network)
• /etc/os-release, /etc/passwd, /etc/group — Host identification
• /var/run/docker.sock — Docker container monitoring

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., monitor.yourdomain.com)
3. Set the container port to 19999
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Netdata container. Consider restricting access to the monitoring dashboard — Netdata does not have built-in authentication by default.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the netdata container pull and start
3. Check the Logs tab for the netdata service. Look for: NETDATA AGENT RUNNING
4. Open https://monitor.yourdomain.com in your browser — you should see the Netdata dashboard with real-time charts
5. Verify that CPU, memory, disk, and network charts show data
6. Check the Docker container monitoring section to see metrics for your other Dokploy services

Troubleshooting

Charts show "no data" for system metrics Verify the read-only host mounts (/proc, /sys) are accessible. Some VPS providers use custom kernels that may not expose all metrics. Check Netdata logs for collector errors — journalctl -u netdata style output appears in the container logs.

Docker container monitoring not working Ensure /var/run/docker.sock is mounted and the Netdata container has read access. On some systems, the Docker socket has restricted permissions. From your server shell, verify: ls -la /var/run/docker.sock.

High memory usage Netdata stores per-second metrics in memory. Reduce retention by editing ../files/netdata-config/netdata.conf and adjusting [db].retention to a lower value (default is 3600 seconds). The dbengine storage mode uses disk for long-term retention.

No authentication on the dashboard Netdata's local dashboard does not include authentication by default. For production use, configure basic authentication in Dokploy's Traefik proxy, or claim the node to Netdata Cloud which provides role-based access control.

---

Learn more about Netdata in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Netdata.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.