Complete Guide to EPD (Easy Project Deployer)

epd is a zero-downtime deployment tool designed to deploy any application to one server or a fleet of servers over standard SSH. It combines zero-downtime blue/green deployments, automatic Let's Encrypt SSL, a shared reverse proxy (Traefik), and multi-host load balancing without requiring Kubernetes or complex container orchestration.

---

Documentation Hub

Explore the topics below for in-depth documentation and examples:

🚀

Getting Started (5 Min)

Step-by-step tutorial: initialize, configure, setup, and deploy your first application.

📦

Prerequisites & Installation

Local and remote server requirements, package manager commands, and SSH setup.

🏗️

Architecture & Request Flow

How Traefik routes incoming traffic, filesystem layouts, and zero-daemon design.

🔄

Zero-Downtime Blue/Green

The deployment lifecycle: idle slot booting, health checks, atomic route switching, and draining.

🐳

Docker vs. Process Mode

Run containerized apps with Docker, or deploy plain Bun/Node/Python code via PM2.

🌐

Multi-Site on Single VPS

Host dozens of independent domains on a single host without port collisions.

⚡

High Availability & Clusters

Cross-host load balancing, private VPC network routing, and rolling rollouts.

🔀

Advanced Routing & Traefik

Path stripping, subdomains, basic auth, redirects, sticky sessions, and wildcard SSL.

🔒

Secrets & Environments

Safe secret resolution, destination overlays (staging vs production), and chmod 0600 storage.

🗄️

Accessories (Databases & Caches)

Persistent Postgres, Redis, and MinIO containers with volume management and web UIs.

🤖

GitHub Actions CI/CD

Automated continuous deployment on every git push with a 20-line workflow file.

☁️

Hetzner Cloud & DNS

Dynamic server targets, CLI provisioning, and Cloudflare/Hetzner DNS auto-sync.

💻

CLI Commands Reference

Full documentation of commands, options, and flags from epd init to epd remove.

⚙️

Configuration Reference (epd.yml)

Complete annotated YAML schema specification with every possible configuration key.

🛠️

Troubleshooting & Operations

Resolving deployment locks, diagnosing probe timeouts, and disaster recovery.

---

Guide Topics

1. Key Features & Architecture

epd routes incoming traffic on ports 80/443 through a shared Traefik proxy and isolates each app's configuration.

Internet (HTTP:80 / HTTPS:443)
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│ SERVER (Host)                                               │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Shared Traefik Proxy (:80 / :443)                     │  │
│  │ Automatically routes traffic based on dynamic YAML    │  │
│  └────────┬─────────────────────────────┬────────────────┘  │
│           │                             │                   │
│           ▼                             ▼                   │
│  ┌─────────────────────┐       ┌────────────────────────┐  │
│  │ App 1 (Blog)        │       │ App 2 (Store)          │  │
│  │ Blue/Green replicas │       │ Blue/Green replicas    │  │
│  │ blog.example.com    │       │ store.example.com      │  │
│  └─────────────────────┘       └────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

👉 Read the complete Architecture Guide →

---

2. Prerequisites & Installation

Install epd using Bun, NPM, or as a standalone Linux binary:

bun

bun install -g @fabioplunser/epd

npm

npm install -g @fabioplunser/epd

standalone binary

curl -fsSL https://github.com/FabioPlunser/epd/releases/latest/download/epd-linux-x64 -o /usr/local/bin/epd
chmod +x /usr/local/bin/epd

👉 Read the full Installation Guide →

---

3. Quick Start (5 Minutes)

Get an app up and running in 4 simple commands:

cd my-project

# 1. Initialize epd.yml
epd init

# 2. Setup your servers (Docker/PM2, Traefik, networks) and run first deploy
epd setup

# 3. Deploy anytime with zero downtime
epd deploy

👉 Follow the Step-by-Step Getting Started Walkthrough →

---

4. Deployment Modes: Docker vs. Process

Choose between containerized Docker builds and native PM2 process execution for ultra-low memory footprints:

• mode: docker: Containerized replicas, isolated bridge network, optional registry.
• mode: process: No Docker required on server. Uploads code via rsync and manages replicas with PM2.

👉 Read the Deployment Modes Guide →

---

5. The Blue/Green Zero-Downtime Lifecycle

Every deploy starts the new version in an alternate slot (blue vs green), verifies health probes, and performs an atomic route switch in Traefik before draining the old slot.

# Instant rollback if needed
epd rollback

👉 Read the Zero-Downtime Blue/Green Guide →

---

6. Multi-Site Hosting on a Single VPS

Deploy multiple completely different applications to the same server. Each app maintains its own dynamic route file under /var/lib/epd/proxy/dynamic/<app>.yml with independent Let's Encrypt SSL certificates.

👉 Read the Multi-Site Hosting Guide →

---

7. High Availability & Multi-Server Clustering

Deploy across multiple servers with rolling updates (strategy: rolling) and enable cross-host routing (proxy.cross_host: true) so requests are balanced across the whole fleet.

👉 Read the High Availability Guide →

---

8. Advanced Routing & Traefik Features

Configure paths, subdomains, prefix stripping, HTTP basic auth, redirects (301/302), custom headers, and sticky sessions:

servers:
  web:
    hosts: [203.0.113.10]
    port: 3000
    routes:
      - host: example.com
      - host: api.example.com
        port: 8080
      - host: example.com
        path: /admin
        strip_path: true
        basic_auth: ["admin:$apr1$xyz..."]

👉 Read the Advanced Routing Guide →

---

9. Automated DNS & Hetzner Cloud

Automatically synchronize A/AAAA records with Cloudflare or Hetzner DNS, and provision servers dynamically with epd hetzner:

# Inspect & sync DNS
epd dns status
epd dns sync

# Manage Hetzner Cloud servers
epd hetzner list
epd hetzner create prod-web-1 --setup

👉 Read the Hetzner Cloud & DNS Guide →

---

10. Automated CI/CD with GitHub Actions

Abstract your entire deployment into epd.yml and deploy automatically on every git push:

- name: Deploy with EPD
  run: npx @fabioplunser/epd deploy
  env:
    SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

👉 Read the GitHub Actions CI/CD Guide →

---

11. Secrets & Environment Management

Keep secrets safe with 0600 root permissions on the host server and support multi-environment overlays (epd deploy -d staging).

👉 Read the Secrets & Environment Guide →

---

12. Persistent Accessories

Run stateful databases (Postgres, MySQL), caches (Redis), or storage (MinIO) alongside your apps with dedicated volumes and Traefik web routing.

👉 Read the Accessories Guide →

---

13. CLI Reference & Configuration Reference

Look up every command and configuration option:

👉 View CLI Commands Reference →
👉 View Configuration Schema Reference (epd.yml) →
👉 View Operations & Troubleshooting Guide →