Prerequisites & Installation

Everything you need to prepare your development environment and target servers for epd.

---

Local System Requirements

epd runs on your local development machine or inside a CI runner (such as GitHub Actions).

• Operating System: Linux or macOS (or Windows via WSL2).
• Standalone Binary: No local runtimes (Node.js, Bun, Python) are required when using the standalone installer.
• Tools:
  • OpenSSH client (ssh).
  • Docker Desktop or Docker Engine (required locally only if using mode: docker to build images).
  • rsync (required if using mode: process).

---

Server Requirements

epd communicates over standard SSH. No custom agent daemons or background control planes need to run on the server.

• Operating System: Any 64-bit Linux distribution:
  • Ubuntu 20.04 / 22.04 / 24.04 LTS (recommended)
  • Debian 11 / 12
  • Fedora 39+ / AlmaLinux / Rocky Linux
  • Arch Linux / Alpine Linux
• SSH Access:
  • Open SSH port (default: 22).
  • Root login or a user allowed to run sudo.
  • Password or SSH key authentication.
• Firewall & Ports:
  • Port 80 (HTTP): Required for Let's Encrypt HTTP-01 challenge and HTTP traffic redirection.
  • Port 443 (HTTPS): Required for encrypted TLS/SSL traffic.
  • Port 22 (SSH): Required for deployment and server management.

Automatic Server Provisioning

epd setup automatically installs Docker, Traefik, curl, and necessary host utilities. You only need a clean server with SSH access!

---

Installing EPD

Option 1: Zero-Dependency Standalone Installer (Recommended)

Installs the pre-compiled, self-contained standalone executable directly for Linux (x64 / arm64) or macOS (Apple Silicon / Intel). Requires no Node.js or Bun runtime:

curl -fsSL https://raw.githubusercontent.com/FabioPlunser/epd/main/install.sh | bash

Option 2: Bun

bun install -g @fabioplunser/epd

Option 3: NPM / PNPM / Yarn

npm

npm install -g @fabioplunser/epd

pnpm

pnpm add -g @fabioplunser/epd

yarn

yarn global add @fabioplunser/epd

Option 4: Run via npx / bunx Without Installation

npx @fabioplunser/epd deploy
# or
bunx @fabioplunser/epd deploy

---

Automated Server & SSH Setup

epd makes server onboarding effortless:

When running epd setup against a fresh server:

1. Key Detection: EPD checks for existing local keys (~/.ssh/id_ed25519, ~/.ssh/gh_deploy, etc.) or loads keys from your active ssh-agent. If none exist, it generates a secure Ed25519 key for you.
2. One-Time Password Authentication: If key authentication is not yet authorized on the remote server, EPD interactively prompts for the server password in your terminal.
3. Automated Key Installation: EPD installs the public key to ~/.ssh/authorized_keys with secure permissions (0700 / 0600).
4. Passwordless Sudo Configuration: If deploying with a non-root user (e.g. fabio), EPD uses the provided password to configure passwordless sudo rules in /etc/sudoers.d/epd.
5. Never Asked Again: From that point on, all deploys, rollbacks, and log streams run completely passwordless and non-interactively!

---

Pre-flight Diagnostics

Before deploying, you can run epd doctor to verify your entire local and remote setup:

epd doctor

It validates:

• Local runtime, Git working tree, and Docker engine status
• SSH client and private key permissions (0600)
• epd.yml schema and required .env secret availability
• Remote server connectivity, passwordless sudo, Docker health, disk space, and deploy locks