DocksySelf-hosting & security
Docksy runs entirely on your infrastructure. Here's what it stores, what it talks to, and how to keep it locked down.
Architecture
- Control plane: one container (
ghcr.io/osmanyousaaf/docksy) running the Node API, the web UI and background jobs, with SQLite as the database. All state lives in/data. - Your servers: Docker, the
docksy-proxyCaddy container (80/443), your app containers, and thedocksy-agentmetrics service. - Control plane → server: SSH with Docksy's own ed25519 key. Connections are pooled and closed after 60 seconds idle.
- Server → control plane: the agent POSTs metrics over HTTPS with a per-server token. No inbound ports are needed on servers except 80/443 for your apps.
What Docksy stores
| Data | Protection |
|---|---|
| Passwords | Salted scrypt hash |
| API tokens, agent tokens, sessions | Stored as SHA-256 hashes. The plaintext is shown once |
| Env vars, git tokens, S3 secrets, channel secrets | Encrypted at rest (AES-256-GCM) with DOCKSY_SECRET |
| SSH private key | /data/keys/id_ed25519. Keep the /data volume private |
| Metrics, logs, activity | SQLite in /data, with retention limits |
Back up /data, and keep DOCKSY_SECRET somewhere safe. Without the secret, the encrypted values can't be recovered.
Network calls
Docksy makes no telemetry, analytics, licence or update calls. It contacts:
- your servers (SSH)
- your git host, when cloning (from your server)
- your notification channels (Discord, Slack, Telegram, webhooks, SMTP)
- your S3 endpoint, if configured
- the URLs you set up uptime checks for
Servers download Docker from get.docker.com during provisioning, and the agent binary from your Docksy instance (falling back to GitHub Releases).
Hardening checklist
- Serve the dashboard over HTTPS behind a reverse proxy, and set the Public URL to the https address.
- Restrict port 8080 to localhost or your VPN, and expose only the proxy.
- Use a strong owner password. Login is rate-limited (10 attempts per minute per IP).
- Use read-scoped API tokens wherever you can, one token per tool or person, and revoke unused ones.
- On app servers, allow SSH (22) only from the Docksy host's IP.
- Keep Docksy updated:
docker compose pull && docker compose up -d. - Review Settings → Activity. Every write is logged with its actor.
Roles
Users are owner, admin or viewer. API tokens are scoped full or read.
Reporting a vulnerability
Please don't open a public issue. Use GitHub's private vulnerability reporting. See SECURITY.md for scope and timelines.