@fabioplunser/epd 0.1.0

package/docs/guide.md

@@ -0,0 +1,576 @@
+# 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.
+
+---
+
+## Table of Contents
+
+1. [Key Features & Architecture](#1-key-features--architecture)
+2. [Prerequisites & Installation](#2-prerequisites--installation)
+3. [Quick Start (5 Minutes)](#3-quick-start-5-minutes)
+4. [Deployment Modes: Docker vs. Process](#4-deployment-modes-docker-vs-process)
+5. [The Blue/Green Zero-Downtime Lifecycle](#5-the-bluegreen-zero-downtime-lifecycle)
+6. [Multi-Site Hosting on a Single VPS](#6-multi-site-hosting-on-a-single-vps)
+7. [High Availability & Multi-Server Clustering](#7-high-availability--multi-server-clustering)
+8. [Advanced Routing & Traefik Features](#8-advanced-routing--traefik-features)
+9. [Secrets & Environment Management](#9-secrets--environment-management)
+10. [Accessories (Databases, Caches & Dashboards)](#10-accessories-databases-caches--dashboards)
+11. [CLI Commands Reference](#11-cli-commands-reference)
+12. [Configuration Reference (`epd.yml`)](#12-configuration-reference-epdyml)
+13. [Operations, Troubleshooting & Disaster Recovery](#13-operations-troubleshooting--disaster-recovery)
+
+---
+
+## 1. Key Features & Architecture
+
+```
+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      │  │
+│  └─────────────────────┘       └────────────────────────┘  │
+│           │                                                 │
+│           ▼                                                 │
+│  ┌─────────────────────┐                                    │
+│  │ Accessory: Postgres │                                    │
+│  │ /var/lib/epd/...    │                                    │
+│  └─────────────────────┘                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Why epd?
+- **Many Sites on One Server**: Every app maintains its own isolated dynamic routing file under `/var/lib/epd/proxy/dynamic/<app>.yml`. They share one global Traefik instance. Adding or removing an application leaves other apps on the same machine completely untouched.
+- **Docker Optional (`mode: process`)**: If you don't want containers, `epd` uploads your code via `rsync`, installs dependencies, and manages processes using `pm2` with the same blue/green slot switching, health checks, and rollbacks.
+- **True Zero Downtime**: The existing version continues serving live traffic until the new version passes all health checks and Traefik switches traffic. Old replicas are drained gracefully before being stopped.
+- **Cross-Host Failover (`proxy.cross_host: true`)**: With multi-server setups, each server's proxy can route requests across the entire fleet. If a server goes offline, the other nodes immediately absorb the traffic.
+- **SSH Only**: No agent daemons, no control planes, no vendor lock-in.
+
+---
+
+## 2. Prerequisites & Installation
+
+### Requirements
+- **Local Machine**:
+  - [Bun](https://bun.sh) (v1.1+)
+  - `ssh` client
+  - `docker` (if using `mode: docker`)
+  - `rsync` (if using `mode: process`)
+- **Remote Server(s)**:
+  - Any modern Linux machine (Ubuntu, Debian, Fedora, Arch, Alpine, etc.)
+  - Open SSH port with root or passwordless `sudo` access
+
+### Installation
+
+Install globally using Bun:
+```bash
+bun install -g epd
+```
+
+Or run directly from source or git:
+```bash
+git clone https://github.com/FabioPlunser/EPD.git
+cd EPD && bun install
+bun run src/cli.ts --help
+```
+
+To compile a standalone, self-contained binary (no Bun runtime required on your local machine):
+```bash
+bun run build    # Produces dist/epd
+sudo cp dist/epd /usr/local/bin/epd
+```
+
+---
+
+## 3. Quick Start (5 Minutes)
+
+### Step 1: Initialize Your Project
+From inside your application directory:
+```bash
+epd init
+```
+This interactive command detects your runtime (Node, Bun, Python, Go, Ruby, etc.), suggests sensible defaults, creates `epd.yml`, and optionally generates a starter `Dockerfile`.
+
+### Step 2: Configure Your Servers
+Edit `epd.yml`:
+```yaml
+name: my-app
+mode: docker
+image: my-app
+
+ssh:
+  user: root
+
+servers:
+  web:
+    hosts: [203.0.113.10]
+    port: 3000
+    domains: [myapp.example.com]
+
+proxy:
+  email: admin@example.com
+```
+
+### Step 3: Run Server Setup
+```bash
+epd setup
+```
+`epd setup`:
+1. Verifies SSH connectivity.
+2. Installs Docker (or PM2 and Node/Bun for process mode) if not already installed.
+3. Sets up the directory structure and reserved port blocks.
+4. Starts the shared Traefik proxy.
+5. Deploys your project.
+
+### Step 4: Subsequent Deployments
+For every change thereafter:
+```bash
+epd deploy
+```
+
+---
+
+## 4. Deployment Modes: Docker vs. Process
+
+`epd` supports two distinct runtimes configured via the top-level `mode` field.
+
+### Mode: `docker` (Default)
+In Docker mode:
+1. `epd` builds an image locally (using BuildKit / buildx if available) tagged with the commit SHA.
+2. If a `registry:` is specified, the image is pushed and pulled by servers. If omitted, `epd` streams the image directly over SSH (`docker save | gzip | ssh ... docker load`).
+3. Replicas run in containers on a shared Docker bridge network (`epd`).
+4. Replicas communicate with Traefik using internal container DNS names (`http://epd-<app>-<service>-<slot>-<replica>:<port>`).
+
+```yaml
+mode: docker
+image: ghcr.io/my-org/my-app
+registry:
+  server: ghcr.io
+  username: my-user
+  password: ${GITHUB_TOKEN}
+```
+
+### Mode: `process` (No Docker on Server)
+In process mode:
+1. No Docker is needed on the remote host.
+2. `epd` uploads your code via `rsync` (or clean `git archive`) into `/var/lib/epd/apps/<app>/releases/<version>`.
+3. Runs your `install` and `build` commands on the host.
+4. Starts each replica under `pm2` with unique assigned host ports and environment variables.
+5. Traefik runs as a native binary managed by PM2, routing traffic to localhost ports.
+
+```yaml
+mode: process
+
+process:
+  install: bun install --frozen-lockfile
+  build: bun run build
+  start: bun run start
+  exclude: [".git", "node_modules", ".env", "dist"]
+
+servers:
+  web:
+    hosts: [203.0.113.10]
+    replicas: 2
+    port: 3000
+    domains: [myapp.example.com]
+
+proxy:
+  ssl: false
+```
+
+---
+
+## 5. The Blue/Green Zero-Downtime Lifecycle
+
+Every deploy follows an automated zero-downtime sequence:
+
+```
+[Build & Push/Ship]
+        │
+        ▼
+[Start New Slot (e.g. Green)] ───► New replicas start on alternative slot
+        │
+        ▼
+[Health Probe Verification]   ───► If probes fail: Green is removed, Blue stays live!
+        │
+        ▼
+[Atomic Route Switch]         ───► Traefik dynamic config updated to point to Green
+        │
+        ▼
+[Drain & Retire Old Slot]     ───► In-flight requests complete; Blue slot retired
+```
+
+1. **Slots**: Each service alternates between `blue` and `green`.
+2. **Health Check**: Before any routing changes, `epd` executes an in-server probe against every new replica.
+3. **Safety Fallback**: If health checks fail or timeout, the new slot is killed and the current slot remains in service. Zero traffic is dropped.
+4. **Instant Rollback**: Because previous releases and images remain on the server, `epd rollback` can reactivate the previous version within seconds without rebuilding:
+   ```bash
+   epd rollback
+   ```
+
+---
+
+## 6. Multi-Site Hosting on a Single VPS
+
+Kamal and other deploy tools often assume ownership of ports 80/443, making it painful to run multiple distinct web apps on a single machine.
+
+With `epd`, every application writes its own isolated configuration file into Traefik's dynamic directory:
+- Site A (`epd.yml` with `name: blog`): writes `/var/lib/epd/proxy/dynamic/blog.yml`
+- Site B (`epd.yml` with `name: shop`): writes `/var/lib/epd/proxy/dynamic/shop.yml`
+
+Both applications share the same server IP, the same Traefik instance, and automatic Let's Encrypt certificates without conflict. Removing Site B (`epd remove`) removes only `shop.yml`, leaving Site A operating seamlessly.
+
+---
+
+## 7. High Availability & Multi-Server Clustering
+
+### Across-Host Load Balancing (`proxy.cross_host: true`)
+
+By default, Traefik routes traffic to replicas located on its own server. When you have multiple servers behind round-robin DNS or a cloud load balancer, set `proxy.cross_host: true`:
+
+```yaml
+proxy:
+  cross_host: true
+  private_ips:
+    203.0.113.10: 10.0.0.10
+    203.0.113.11: 10.0.0.11
+
+servers:
+  web:
+    hosts: [203.0.113.10, 203.0.113.11]
+    replicas: 2
+    port: 3000
+    domains: [example.com]
+```
+
+With `cross_host: true`:
+- The application port is published on each host (bound to the private IP when specified).
+- Traefik on Server A balances across all replicas on Server A **and** Server B.
+- If Server B goes down, visitors hitting Server B's DNS address will still be routed to Server A by Server A's proxy, guaranteeing high availability.
+
+### Deployment Strategy
+Control rolling vs. parallel execution across multiple hosts:
+```yaml
+strategy: rolling   # Default: rolls one host at a time, keeping the cluster serving
+# strategy: parallel # Deploys to all hosts simultaneously
+```
+
+---
+
+## 8. Advanced Routing & Traefik Features
+
+Use the `routes:` block under any server group for fine-grained routing control:
+
+```yaml
+servers:
+  web:
+    hosts: [203.0.113.10]
+    port: 3000
+    routes:
+      # 1. Standard Domain
+      - host: example.com
+
+      # 2. Subdomain to different container port
+      - host: api.example.com
+        port: 8080
+
+      # 3. Path-based routing with prefix stripping and Basic Auth
+      - host: example.com
+        path: /admin
+        port: 4000
+        strip_path: true
+        basic_auth:
+          - "admin:$apr1$xyz$0123456789abcdefghijk."
+
+      # 4. Domain Redirect (HTTP 301)
+      - host: www.example.com
+        redirect: https://example.com
+
+      # 5. Temporary Redirect (HTTP 302)
+      - host: promo.example.com
+        redirect: https://example.com/special
+        permanent: false
+
+      # 6. Sticky Session Load Balancing (Cookie pinned)
+      - host: app.example.com
+        path: /socket
+        sticky: true
+
+      # 7. Custom Headers
+      - host: secure.example.com
+        headers:
+          X-Frame-Options: "DENY"
+          X-Content-Type-Options: "nosniff"
+
+      # 8. Wildcard Subdomains (requires DNS challenge)
+      - host: "*.example.com"
+        priority: 1
+```
+
+### Let's Encrypt DNS Challenge
+For wildcard certificates (`*.example.com`) or multi-server setups:
+```yaml
+proxy:
+  challenge: dns
+  dns_provider: cloudflare
+  dns_env: [CF_DNS_API_TOKEN]
+```
+
+---
+
+## 9. Secrets & Environment Management
+
+`epd` ensures secrets are never checked into git, never printed in `docker inspect`, and never written to shell histories.
+
+### Environment Declarations
+```yaml
+env:
+  clear:
+    NODE_ENV: production
+    LOG_LEVEL: info
+  secret:
+    - DATABASE_URL
+    - STRIPE_SECRET_KEY
+```
+
+### How Secret Resolution Works
+1. When you run `epd deploy`, variables in `env.secret` are read from:
+   - Your local environment (`export DATABASE_URL=...`)
+   - `.env` / `.env.local` in your project root
+   - `.env.<destination>` (when using `--destination`)
+2. On the server, `epd` writes a `0600` root-owned environment file.
+3. Containers read secrets via `--env-file`; process mode loads them into PM2 environments.
+
+### Destination Overlays
+Manage staging vs. production effortlessly:
+```bash
+epd deploy -d staging
+```
+Merges `epd.staging.yml` over `epd.yml` and loads `.env.staging`.
+
+---
+
+## 10. Accessories (Databases, Caches & Dashboards)
+
+Accessories are persistent companion containers (like PostgreSQL, Redis, MinIO, or Adminer) that `epd` provisions and manages alongside your app. Unlike application containers, accessories are **not** replaced on every deploy.
+
+```yaml
+accessories:
+  db:
+    image: postgres:17
+    host: 203.0.113.10
+    env:
+      clear:
+        POSTGRES_DB: myapp
+      secret:
+        - POSTGRES_PASSWORD
+    volumes:
+      - /var/lib/epd/volumes/myapp-db:/var/lib/postgresql/data
+    ports:
+      - "127.0.0.1:5432:5432"
+
+  redis:
+    image: redis:7-alpine
+    host: 203.0.113.10
+    volumes:
+      - /var/lib/epd/volumes/myapp-redis:/data
+
+  # Accessory with public HTTP routing through Traefik
+  db_ui:
+    image: adminer:latest
+    host: 203.0.113.10
+    port: 8080
+    domains: [db.myapp.example.com]
+```
+
+### Managing Accessories
+- **View accessory status**: `epd status` shows accessory state and ports.
+- **View accessory logs**: `epd logs --accessory db -f`
+- **Execute commands in an accessory**: `epd exec --accessory db -i -- psql -U myapp`
+- **Recreate accessory container**: `epd deploy --recreate-accessories`
+- **Inspect Docker run command**: `epd docker-command` prints the exact `docker run` command for each accessory.
+
+---
+
+## 11. CLI Commands Reference
+
+| Command | Flags | Description |
+|---|---|---|
+| `epd init` | `--name`, `--mode`, `--host`, `--domain`, `--port`, `--dockerfile` | Initialize a new `epd.yml` for the current project. |
+| `epd setup` | `--skip-deploy`, `--host` | Install prerequisites on servers, start the proxy, and deploy. |
+| `epd deploy` | `--version`, `--no-build`, `--service`, `--host`, `--skip-health`, `--skip-hooks`, `--skip-lock`, `--recreate-accessories`, `-d` | Build and deploy with zero downtime. |
+| `epd redeploy` | `--service`, `--host`, `--skip-health`, `--skip-lock` | Restart the current version without rebuilding or uploading. |
+| `epd rollback [v]`| `--list`, `--service`, `--host` | Roll back to the previous version or a specified version. |
+| `epd status` | `--json` | Show running replicas, slots, health status, and live routes. |
+| `epd logs` | `-f/--follow`, `-n/--lines`, `--service`, `--accessory`, `--host`, `--grep`, `--since` | View or tail logs from servers, services, or accessories. |
+| `epd exec -- <cmd>`| `--host`, `--service`, `--accessory`, `--reuse`, `-i` | Run a one-off command with the app's image and environment. |
+| `epd shell` | `--host`, `--service`, `--accessory` | Open an interactive shell inside a running replica or accessory. |
+| `epd proxy <cmd>` | `status`, `reboot`, `logs`, `routes`, `remove` (`--host`, `-f`, `-n`) | Inspect, follow logs, or restart the shared Traefik proxy. |
+| `epd config` | `--json`, `--raw`, `--traefik` | Validate and print the resolved configuration or Traefik specs. |
+| `epd docker-command`| `--host`, `--service`, `--slot`, `--version`, `--replica` | Output copy-pasteable `docker run` / `pm2` commands. |
+| `epd lock <cmd>` | `status`, `release` | Inspect or clear the atomic deploy lock. |
+| `epd remove` | `-y/--yes`, `--keep-data`, `--host` | Stop this app, remove its routes, and delete files from servers. |
+
+---
+
+## 12. Configuration Reference (`epd.yml`)
+
+Full annotated schema of `epd.yml`:
+
+```yaml
+name: myapp                    # App name (alphanumeric, dashes, underscores)
+mode: docker                   # docker | process
+
+# Docker Build Settings
+image: ghcr.io/org/myapp       # Docker image repository (docker mode)
+registry:                      # Optional: registry credentials
+  server: ghcr.io
+  username: deployer
+  password: ${GITHUB_TOKEN}    # Interpolated from environment
+build:
+  dockerfile: Dockerfile       # Relative path to Dockerfile
+  context: .                   # Build context
+  platform: linux/amd64        # Target architecture
+  args:                        # Build arguments
+    COMMIT_SHA: ${GIT_SHA:-dev}
+  secrets:                     # BuildKit build secrets
+    npm_token: NPM_TOKEN
+
+# Process Mode Settings
+process:
+  install: bun install         # Dependency install command
+  build: bun run build         # Build command
+  start: bun run start         # Start command (receives $PORT)
+  exclude: [".git", "node_modules"]
+  source: rsync                # rsync | git
+
+# SSH Configuration
+ssh:
+  user: root                   # Remote SSH user
+  port: 22                     # Remote SSH port
+  key: ~/.ssh/id_ed25519       # Optional explicit private key
+  proxy_jump: bastion.net      # Optional Jump host / Bastion
+  options:                     # Extra SSH options
+    - ServerAliveInterval=30
+
+# Server Definitions
+servers:
+  web:
+    hosts: [203.0.113.10]      # Server IPs or hostnames
+    replicas: 2                # Replicas per host
+    port: 3000                 # Internal application port
+    domains: [myapp.com]       # Domains to serve
+    cpus: "2.0"                # CPU limit
+    memory: "1g"               # Memory limit
+    drain: 10                  # Seconds to drain old slot
+    stop_timeout: 15           # SIGTERM grace period in seconds
+    volumes:
+      - /var/lib/epd/volumes/uploads:/app/uploads
+    env:
+      clear:
+        APP_ENV: production
+      secret:
+        - APP_SECRET
+
+  worker:                      # Background worker (no exposed routes)
+    hosts: [203.0.113.10]
+    replicas: 1
+    command: bun run worker.ts
+
+# Shared Reverse Proxy
+proxy:
+  enabled: true
+  ssl: true                    # Automatically request Let's Encrypt certificates
+  email: admin@myapp.com       # Registration email for ACME
+  challenge: http              # http | dns | tlsalpn
+  entrypoints:
+    web: 80
+    websecure: 443
+  cross_host: false            # Enable cross-server load balancing
+  reload_wait: 3               # Throttle duration for route changes
+
+# Health Check Settings
+healthcheck:
+  path: /health                # HTTP path to probe (null for TCP-only check)
+  status: 200-399              # Acceptable status codes
+  timeout: 60                  # Timeout in seconds
+  interval: 2                  # Seconds between probe attempts
+  delay: 1                     # Initial delay before probing
+
+# Global Environment
+env:
+  clear:
+    NODE_ENV: production
+  secret:
+    - DATABASE_URL
+
+# Lifecycle Hooks
+hooks:
+  pre_build: ./scripts/lint.sh
+  pre_deploy: ./scripts/db-migrate.sh
+  post_deploy: ./scripts/notify-slack.sh
+  on_failure: ./scripts/alert-ops.sh
+
+# Deployment Strategy
+strategy: rolling              # rolling | parallel
+keep_releases: 5               # Retain last N images / release directories
+remote_root: /var/lib/epd      # Root directory on remote hosts
+```
+
+---
+
+## 13. Operations, Troubleshooting & Disaster Recovery
+
+### Common Scenarios
+
+#### 1. Deployment Fails on Health Check
+- **What Happened**: New replicas started, but `/health` (or `/`) did not return `200-399` within the timeout.
+- **Result**: The new replicas were automatically purged. The previous slot is still live. Zero downtime occurred.
+- **Investigation**:
+  ```bash
+  epd logs --service web --lines 50
+  ```
+- **Remedy**: Fix the issue, or adjust `healthcheck.timeout` / `healthcheck.path` in `epd.yml`.
+
+#### 2. Deploy Lock Held
+- **What Happened**: A previous deploy process was terminated abruptly (e.g. laptop closed or killed with `kill -9`).
+- **Investigation**:
+  ```bash
+  epd lock status
+  ```
+- **Remedy**:
+  ```bash
+  epd lock release
+  ```
+
+#### 3. Inspecting Server Routes
+To see the exact Traefik route file epd generated on the server:
+```bash
+epd proxy routes
+```
+
+#### 4. Checking Proxy Health & Restarting
+If you updated global proxy options (such as adding an entrypoint or enabling the dashboard):
+```bash
+epd proxy status
+epd proxy reboot
+```
+
+#### 5. Completely Removing an Application
+When decommissioning an app from your servers:
+```bash
+epd remove
+```
+This cleans up all replicas, releases, and Traefik dynamic routes without touching any other epd applications sharing the machine.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@fabioplunser/epd",
+  "version": "0.1.0",
+  "description": "Easy Project Deployer — deploy any project to one or many servers with Docker or PM2, fronted by Traefik.",
+  "type": "module",
+  "author": "Fabio Plünser",
+  "license": "MIT",
+  "homepage": "https://github.com/FabioPlunser/epd#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FabioPlunser/epd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/FabioPlunser/epd/issues"
+  },
+  "keywords": [
+    "deployment",
+    "docker",
+    "traefik",
+    "zero-downtime",
+    "devops",
+    "pm2",
+    "cli"
+  ],
+  "bin": {
+    "epd": "bin/epd.js",
+    "edp": "bin/epd.js"
+  },
+  "files": [
+    "bin",
+    "dist/cli.js",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "bun run src/cli.ts",
+    "build": "bun run build:bundle && bun run build:binary",
+    "build:bundle": "bun build src/cli.ts --target=bun --outfile dist/cli.js",
+    "build:binary": "bun build --compile --minify --sourcemap src/cli.ts --outfile dist/epd",
+    "build:binaries": "bun run scripts/build-all.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build:bundle"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}