Modular Linux & Docker Node Provisioning Toolkit with Control Plane Auto-Enrollment.
Turn budget VPS instances (<= 1 GB RAM, 1 vCPU) into lean, robust Docker worker nodes consuming only ~90β110 MB idle RAM.
English | Π ΡΡΡΠΊΠΈΠΉ | Agent & LLM Guide
Modern self-hosted PaaS panels (like Dokploy, Coolify, and others) are great, but their default remote node setup is often heavyweight:
- Automatically initializes Docker Swarm mode (raft consensus, swarm overlay).
- Runs an in-node Traefik Ingress container (consuming 60β100 MB RAM).
- Installs multi-gigabyte build tools (Nixpacks, Buildpacks, Railpack).
- Deploys continuous monitoring scrapers (Vector, cAdvisor, Node Exporter).
On budget cloud VPS servers ($3β$5/month with 512 MB β 1 GB RAM), this default stack consumes 450β550 MB RAM just idling. Pulling a multi-layer container image (docker pull) on a single vCPU causes catastrophic OOM (Out-of-Memory) crashes.
server-setup provides a zero-dependency, production-tested toolkit to:
- Slash Idle Memory by 80%: Run Docker with
crunand optimizeddaemon.json, keeping total OS + Docker idle footprint under ~100 MB RAM. - Eliminate OOM Crashes: Tiered memory protection with in-memory ZRAM (LZ4) and fallback SSD swapfile.
- One-Command Auto-Enrollment (
Agent Join): Run one command on the new server. It optimizes the machine, pulls your panel's SSH public key, adds it toauthorized_keys, and registers the server into Dokploy or Coolify via API with zero manual clicks in the UI. - Pluggable Architecture:
core/: Memory & Docker low-RAM optimization.adapters/: Dokploy, Coolify, Portainer, and Standalone.modules/: Cloudflare Tunnel, Caddy micro-proxy, Docker Auto-Prune, and Zero-Overhead Telemetry.
- 100% Upstream Compatible: Requires 0 changes or patches to Dokploy or Coolify. Works with official upstream releases.
| Component | Default Node | With server-setup |
Savings |
|---|---|---|---|
| Linux OS Baseline | ~70 MB | ~50 MB | Caps journald, cleans services |
dockerd |
~90 MB | ~40 MB | BuildKit off, GOMEMLIMIT=128MiB |
containerd |
~45 MB | ~18 MB | CRI disabled, tuned GC |
docker-proxy |
~10 MB / port | 0 MB | Native kernel iptables/nftables |
| Container Shims | ~20 MB / container (runc) |
2β4 MB (crun) |
C-based OCI runtime |
| Docker Swarm Mode | ~75 MB | 0 MB | Standalone Compose mode |
| Traefik Ingress | ~80 MB | 0 MB | External routing / Direct ports |
| Vector / cAdvisor | ~100 MB | 0 MB | Lightweight SSH polling |
| TOTAL Idle RAM | ~450β550 MB | ~90β110 MB | π₯ ~400+ MB freed for your apps! |
Log in to your target server via SSH and run:
curl -sSL https://raw.githubusercontent.com/littfed/server-setup/main/dist/server-setup-standalone.sh | sudo bash -s -- \
--panel dokploy \
--panel-url https://dokploy.example.com \
--api-key dkp_your_api_key_here \
--name "worker-node-01" \
--secure \
--auto-pruneWhat happens automatically:
- Tunes kernel memory (ZRAM LZ4 + swapfile), network (Google BBR, SYN flood defense), and Docker with
crun. - Hardens SSH with anti-lockout protection, configures UFW firewall with
DOCKER-USERchain isolation, and activates adaptive IDS (Fail2ban or CrowdSec). - Connects to Dokploy API (
/api/sshKey.all) and fetches your Dokploy instance's public SSH key. - Authorizes the key in
~/.ssh/authorized_keyswith mode 600. - Auto-detects public IP and registers the node in Dokploy without port conflict.
- The node instantly appears active and green in your Dokploy dashboard!
curl -sSL https://raw.githubusercontent.com/littfed/server-setup/main/dist/server-setup-standalone.sh | sudo bash -s -- \
--panel coolify \
--panel-url https://coolify.example.com \
--api-key your_coolify_token_here \
--name "cool-worker-01" \
--auto-pruneIf you want to prepare any Linux VPS to run Docker with minimal memory consumption, automatic zero-port tunnel ingress, and weekly disk cleanup:
curl -sSL https://raw.githubusercontent.com/littfed/server-setup/main/dist/server-setup-standalone.sh | sudo bash -s -- \
--panel standalone \
--ingress cloudflare \
--cf-token eyJxxxxxxxxxxxxxxxxxx \
--auto-prune \
--telemetry webhook \
--webhook-url https://alert.example.com/webhookAudit your server's public IPv4/IPv6 across 20+ reputation blacklists (Spamhaus, Barracuda, SpamCop, etc.), check ASN/ISP data, and verify rDNS/PTR:
# Standalone run on any machine (checks own public IP)
curl -sSL https://raw.githubusercontent.com/littfed/server-setup/main/dist/server-setup-standalone.sh | bash -s -- --audit-only
# Or audit an arbitrary external IP:
./modules/audit/ip-reputation.sh 1.2.3.4 --dns 9.9.9.9
# Run as pre-flight check before server enrollment (warns if dirty, or aborts with --strict-audit):
curl -sSL https://raw.githubusercontent.com/littfed/server-setup/main/dist/server-setup-standalone.sh | sudo bash -s -- \
--panel dokploy \
--panel-url https://dokploy.example.com \
--api-key dkp_your_api_key_here \
--audit-ip \
--strict-auditCore Options:
--panel <type> Control plane: dokploy | coolify | standalone (default: standalone)
--panel-url <url> URL of the control plane (e.g. https://dokploy.example.com)
--api-key <key> API Key or Token for panel authentication
--name <name> Server display name (default: current hostname)
--port <port> SSH port of this machine (default: 22)
--user <user> SSH username for panel connection (default: current user)
Audit & Reputation Options:
--audit-ip Run IP reputation & blacklist audit on host public IPs
--strict-audit Abort setup if host IP has high risk or is blacklisted
--audit-only Run only IP reputation audit without system or Docker changes
--dns <ip> Custom DNS resolver for DNSBL queries (e.g. 9.9.9.9, 1.1.1.1)
Diagnostics & Benchmark:
--bench, --test Run hardware & network performance benchmark (standalone)
--speedtest Run multi-stream network speedtest (throughput, latency, jitter)
--streams <N> Number of parallel TCP streams for speedtest (default: 4)
--server <id/url> Target specific speedtest server
--quick Run accelerated benchmark or speedtest
--json Emit machine-readable JSON output
Pre-Flight & Rollback:
--skip-preflight Skip pre-flight virtualization, port and resource checks
--rollback [target] Restore configuration snapshot (target: latest | timestamp)
--rollback-list List available configuration snapshots
Ingress Options:
--ingress <type> Ingress provider: none | cloudflare | caddy (default: none)
--cf-token <token> Cloudflare Tunnel token (required for --ingress cloudflare)
--domain <domain> Public domain name (used for --ingress caddy)
--upstream <host:port> Upstream destination (default: 127.0.0.1:3000)
Maintenance Options:
--auto-prune Enable weekly safe Docker prune (default: enabled)
--no-auto-prune Disable Docker auto-prune
--prune-age <age> Age threshold for prune (default: 168h / 7 days)
Security & Hardening Options:
--secure Enable comprehensive security: SSH hardening + Firewall + IDS
--harden-ssh Enable SSH hardening (key-based auth, modern ciphers, timeouts)
--ssh-port <port> SSH port for hardening and firewall (default: 22)
--firewall Enable UFW baseline firewall with DOCKER-USER protection
--open-ports <ports> Comma-separated extra ports to open (e.g. 80,443)
--ids <mode> Intrusion detection engine: auto | fail2ban | crowdsec (default: none)
Telemetry Options:
--telemetry <type> Telemetry mode: none | webhook | telegram (default: none)
--webhook-url <url> Webhook endpoint for JSON metrics and alerts
--tg-token <token> Telegram Bot token for alerts
--tg-chat <chat_id> Telegram Chat ID for alerts
General:
--dry-run Simulate execution without modifying the host
-h, --help Show help message
server-setup/
βββ setup.sh # Unified CLI dispatcher
βββ bundle.sh # Generates standalone self-extracting installer
βββ core/
β βββ preflight.sh # Host sanity check, virtualization detection & auto-adaptation
β βββ time.sh # NTP synchronization (systemd-timesyncd / chrony)
β βββ system.sh # Google BBR, sysctl network hardening, limits, fstrim, updates
β βββ memory.sh # ZRAM, swapfile, sysctl memory tuning
β βββ docker.sh # Docker Engine, crun runtime, daemon.json (log limits: 10m/3 files)
βββ adapters/
β βββ dokploy.sh # Dokploy auto-enrollment adapter
β βββ coolify.sh # Coolify auto-enrollment adapter
β βββ standalone.sh # Headless standalone node adapter
βββ modules/
β βββ audit/
β β βββ ip-reputation.sh # Zero-key IP reputation & threat intelligence audit
β βββ diagnostics/
β β βββ bench.sh # Hardware & network benchmark (CPU steal, I/O IOPS, CDN speed)
β βββ ingress/
β β βββ cloudflare.sh # Cloudflare Tunnel (zero open ports)
β β βββ caddy.sh # Caddy micro-proxy (<20 MB RAM, auto-SSL)
β βββ maintenance/
β β βββ auto-prune.sh # Low-priority systemd timer for image cleanup
β β βββ rollback.sh # Pre-flight snapshots & atomic state rollback
β βββ security/
β β βββ ssh.sh # SSH hardening with anti-lockout key verification
β β βββ firewall.sh # UFW firewall baseline + DOCKER-USER chain isolation
β β βββ ids.sh # Adaptive intrusion detection (Fail2ban vs CrowdSec)
β βββ telemetry/
β βββ health-cron.sh # 0 MB resident RAM metrics reporter
βββ dist/
β βββ server-setup-standalone.sh # Standalone single-file bundle
βββ tests/
β βββ run_all_tests.sh # Test suite runner
β βββ test_core.sh
β βββ test_dokploy_adapter.sh
β βββ test_coolify_adapter.sh
β βββ test_auto_prune.sh
β βββ test_ingress.sh
β βββ test_telemetry.sh
β βββ test_audit.sh
β βββ test_security.sh
β βββ test_diagnostics.sh
β βββ test_rollback.sh
β βββ test_cli.sh
βββ .github/workflows/
β βββ ci.yml # Multi-distro CI (Ubuntu 22.04/24.04, Debian 12)
βββ docs/
β βββ adr/
β β βββ 0001-lightweight-remote-server-profile.md
β β βββ 0002-modular-architecture.md
β βββ agents/ # SDD workflow conventions
βββ GLOSSARY.md # Domain language
βββ CLAUDE.md # AI Assistant rules
βββ LICENSE # MIT License
βββ README.md
Run the automated test suite locally:
./tests/run_all_tests.shBuild the standalone single-file installer:
./bundle.shMIT Β© littfed