v2.0 — Multi-VPS Architecture

Know what every
container costs.

Docker container cost allocation across one or many VPS instances. Deploy lightweight agents, track per-container costs from a central dashboard. Weighted formula based on actual CPU and RAM usage.

Get Started Read the Docs
Architecture

How it works

Each VPS runs a lightweight Go agent that collects raw Docker stats and pushes them to the central server. The central server calculates costs using VPS configuration stored in the database — no local config needed on agents.

Agent collects raw stats
Pushes via API key
Central calculates cost
Dashboard shows totals
VPS A — Hetzner CX42 CPU 23% · RAM 4.2/8GB
VPS B — DO Droplet CPU 11% · RAM 1.8/4GB
VPS C — Vultr CPU 3% · RAM 0.6/2GB
Central Server
Calculates + Stores
Database
PostgreSQL
Dashboard
Chart.js UI

Agent (per VPS)

  1. Reads Docker socket for container stats (CPU%, RAM%, status)
  2. Sends raw stats to central server via POST /api/v1/push
  3. Authenticates via API key generated from dashboard
  4. Retries up to 5× with exponential backoff on failure
  5. No local config needed — VPS specs managed from dashboard

Central Server

  1. Receives raw stats via API key auth
  2. Looks up VPS config (price, weights, specs) from DB
  3. Creates calculator with VPS config & calculates cost report
  4. Saves snapshot to PostgreSQL with per-VPS attribution
  5. Serves aggregated dashboard — total cost across all VPS
Features

Everything you need to track costs

From single VPS to multi-VPS fleet — weighted cost allocation based on actual resource usage.

Multi-VPS Dashboard

Total cost across all VPS, per-container breakdown, trends — all from one central dashboard. Online/offline detection per VPS.

Lightweight Agent

Single Go binary — no Python, no dependencies. Reads Docker socket and pushes raw stats. One-liner deploy via curl pipe.

Smart Cost Formula

Weighted allocation: CPU 50%, RAM 40%, Storage 10%. Fully configurable per VPS from the dashboard — adjust weights in real-time.

Role-based Auth

Admin, Engineer, Management — three access levels. Session-based login with bcrypt password hashing.

Central VPS Config

Add/edit/delete VPS from dashboard. Set price, CPU cores, RAM, storage, weights — all stored in DB. Agent just needs an API key.

Docker + Binary Release

Docker image on GHCR. Binary tarballs for amd64/arm64 on GitHub Releases. Versioned releases with semver tags.

Quick Install

Up and running in 5 minutes

Docker Compose for the central server, one-liner for agents on each VPS.

# Start everything with one command: curl -sL https://raw.githubusercontent.com/edsuwarna/container-cost/main/docker-compose.yml > docker-compose.yml docker compose up -d # Open http://localhost:8081 # Login: admin / change-me # Add VPS → deploy agent → done
# From the VPS you want to monitor: docker run -d --name container-cost-agent \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ ghcr.io/edsuwarna/container-cost:latest \ --mode=agent \ --server=http://CENTRAL_IP:8080 \ --api-key=DCKR_xxx
# Download from GitHub Releases: curl -LO https://github.com/edsuwarna/container-cost/releases/latest/download/container-cost-linux-amd64.tar.gz tar xzf container-cost-linux-amd64.tar.gz sudo install container-cost /usr/local/bin/ # Verify: container-cost --version container-cost --mode=agent --server=http://CENTRAL_IP:8080 --api-key=DCKR_xxx

💡 Agent only needs Docker socket + API key. VPS config (price, specs, weights) is managed from the dashboard.

Documentation

Everything explained

From architecture deep-dive to API reference and troubleshooting.

Overview What, why, who — the big picture Architecture Data flow and system design Quick Start 5-minute setup guide Deployment Central, agent, binary, Docker Configuration Config file, env vars, weights Cost Formula Step-by-step with examples API Reference All endpoints, auth, examples Frontend Dashboard Charts, charts, permissions Development Structure, testing, database Security Auth, keys, best practices Troubleshooting Common issues & fixes FAQ Frequently asked questions