Skip to content

About

Modular Linux & Docker Node Provisioning Toolkit for budget VPS (<=1GB RAM) with Dokploy/Coolify Auto-Enrollment and IP Threat Audit

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

32 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Server Setup πŸš€

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


πŸ’‘ The Problem

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.

🎯 The Solution

server-setup provides a zero-dependency, production-tested toolkit to:

  1. Slash Idle Memory by 80%: Run Docker with crun and optimized daemon.json, keeping total OS + Docker idle footprint under ~100 MB RAM.
  2. Eliminate OOM Crashes: Tiered memory protection with in-memory ZRAM (LZ4) and fallback SSD swapfile.
  3. 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 to authorized_keys, and registers the server into Dokploy or Coolify via API with zero manual clicks in the UI.
  4. 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.
  5. 100% Upstream Compatible: Requires 0 changes or patches to Dokploy or Coolify. Works with official upstream releases.

πŸ“Š Memory Footprint Comparison

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!

⚑ Quick Start

1. Auto-Join to Dokploy (Reverse Registration)

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-prune

What happens automatically:

  1. Tunes kernel memory (ZRAM LZ4 + swapfile), network (Google BBR, SYN flood defense), and Docker with crun.
  2. Hardens SSH with anti-lockout protection, configures UFW firewall with DOCKER-USER chain isolation, and activates adaptive IDS (Fail2ban or CrowdSec).
  3. Connects to Dokploy API (/api/sshKey.all) and fetches your Dokploy instance's public SSH key.
  4. Authorizes the key in ~/.ssh/authorized_keys with mode 600.
  5. Auto-detects public IP and registers the node in Dokploy without port conflict.
  6. The node instantly appears active and green in your Dokploy dashboard!

2. Auto-Join to Coolify

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-prune

3. Standalone Low-RAM Server with Cloudflare Tunnel & Auto-Prune

If 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/webhook

4. IP Reputation & Threat Audit (Zero-Key)

Audit 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-audit

πŸ›  Command-Line Reference

Core 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

πŸ“‚ Repository Structure

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

πŸ§ͺ Testing & Verification

Run the automated test suite locally:

./tests/run_all_tests.sh

Build the standalone single-file installer:

./bundle.sh

πŸ“„ License

MIT Β© littfed

About

Modular Linux & Docker Node Provisioning Toolkit for budget VPS (<=1GB RAM) with Dokploy/Coolify Auto-Enrollment and IP Threat Audit

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages