@fabioplunser/epd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Plünser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,458 @@
+# epd — Easy Project Deployer
+
+Deploy any project to one server or ten, with zero downtime, from a single
+command:
+
+```bash
+epd deploy
+```
+
+epd takes the good ideas from [Kamal](https://kamal-deploy.org) — a config file
+in your repo, SSH as the only requirement, blue/green containers, rollbacks —
+and fixes the two things that get in the way in practice:
+
+- **Many sites on one server.** Every app writes its own routing file for a
+  Traefik instance shared by the whole machine. A second (or tenth) site on the
+  same box is just another `epd.yml`, with its own domains, paths and ports. No
+  fighting over port 80, no proxy that only knows about one app.
+- **You do not have to use Docker.** `mode: process` uploads your project,
+  installs dependencies on the server and runs your own start command
+  (`bun run start`, `node server.js`, anything) under pm2 — with the same
+  blue/green switch, health checks and rollbacks. Traefik runs as a plain
+  binary, so the server needs nothing but SSH.
+
+Multiple machines, load balancing and failover are first-class: replicas are
+balanced by Traefik, and with `cross_host: true` every server's proxy balances
+across every server's replicas, so one machine can serve while another is down.
+
+📖 **For the in-depth user manual and complete configuration reference, see the [Complete Guide](docs/guide.md).**
+
+---
+
+## Install
+
+### Global CLI via NPM or Bun
+
+```bash
+npm install -g @fabioplunser/epd
+# or
+bun install -g @fabioplunser/epd
+```
+
+Once installed, use `epd` anywhere:
+```bash
+epd --help
+```
+
+### Run directly without installing (npx / bunx)
+
+```bash
+npx @fabioplunser/epd deploy
+# or
+bunx @fabioplunser/epd deploy
+```
+
+### Standalone Precompiled Executables (Zero Runtime Dependencies)
+
+Download single-file standalone binaries directly from [GitHub Releases](https://github.com/FabioPlunser/epd/releases):
+- `epd-linux-x64` / `epd-linux-arm64`
+- `epd-darwin-x64` / `epd-darwin-arm64` (macOS Intel & Apple Silicon)
+- `epd-windows-x64.exe`
+
+```bash
+curl -fsSL https://github.com/FabioPlunser/epd/releases/latest/download/epd-linux-x64 -o /usr/local/bin/epd
+chmod +x /usr/local/bin/epd
+```
+
+### From source
+
+```bash
+git clone https://github.com/FabioPlunser/epd.git && cd epd && bun install
+bun run build     # compiles dist/cli.js and dist/epd
+```
+
+You need on **your machine**: `bun`, `ssh`, and `docker` (only for `mode: docker`)
+or `rsync` (only for `mode: process`). You need on **the server**: SSH access.
+`epd setup` installs everything else.
+
+---
+
+## Quick start
+
+```bash
+cd my-project
+epd init          # writes epd.yml (and a Dockerfile if you want one)
+epd setup         # prepares the servers and deploys
+epd deploy        # every time after that
+```
+
+Point your domain's A record at the server(s) first — Traefik requests a
+Let's Encrypt certificate the first time a request arrives for the domain.
+
+---
+
+## What a deploy does
+
+```
+build  →  ship  →  start new replicas  →  health check  →  switch routes  →  retire old
+```
+
+1. Builds and tags the image with your git sha (or uploads the project, in
+   process mode).
+2. Starts the new version on the *other* slot — `blue` and `green` alternate —
+   next to the version that is currently serving.
+3. Waits for every new replica to pass its health check. If any fails, the new
+   replicas are removed and the old version keeps serving. Nothing is switched.
+4. Writes the routing file, waits for the proxy to pick it up, then retires the
+   old replicas after a drain period.
+
+The old version is never stopped before the new one is proven and routed, which
+is what makes the deploy zero-downtime. There is an end-to-end test that hammers
+a site while redeploying it and fails if a single request is not a 200.
+
+---
+
+## Configuration
+
+`epd.yml` lives in your project root. Everything below is optional except
+`name`, one server entry, and — in process mode — a start command.
+
+```yaml
+name: blog
+mode: docker            # docker (build an image) | process (upload + pm2)
+
+image: ghcr.io/me/blog  # docker mode only
+
+registry:               # omit entirely to ship images over SSH instead
+  server: ghcr.io
+  username: me
+  password: ${GITHUB_TOKEN}
+
+build:
+  dockerfile: Dockerfile
+  context: .
+  platform: linux/amd64
+  args:
+    COMMIT: ${GIT_SHA:-dev}
+  secrets:              # id -> env var, exposed to the build via BuildKit
+    npm_token: NPM_TOKEN
+
+ssh:
+  user: root
+  port: 22
+  key: ~/.ssh/id_ed25519
+  proxy_jump: bastion.example.com
+
+servers:
+  web:
+    hosts: [203.0.113.10, 203.0.113.11]
+    replicas: 2         # per host, load balanced by the proxy
+    port: 3000          # the port your app listens on
+    domains: [example.com, www.example.com]
+    env:
+      clear:
+        LOG_LEVEL: info
+      secret:
+        - DATABASE_URL
+    volumes:
+      - /var/lib/epd/volumes/blog-uploads:/app/uploads
+    cpus: "2"
+    memory: 1g
+
+  worker:               # no routes → not exposed, no HTTP health check
+    hosts: [203.0.113.10]
+    command: bun run worker.ts
+
+proxy:
+  ssl: true
+  email: me@example.com
+  challenge: http       # http | dns | tlsalpn
+  entrypoints:
+    web: 80
+    websecure: 443
+  cross_host: false
+  reload_wait: 3
+
+healthcheck:
+  path: /up
+  status: 200-399
+  timeout: 60
+  interval: 2
+
+env:
+  clear:
+    NODE_ENV: production
+  secret:
+    - SECRET_KEY_BASE   # read from your shell or .env at deploy time
+
+accessories:
+  db:
+    image: postgres:17
+    host: 203.0.113.10
+    env:
+      clear: { POSTGRES_DB: blog }
+      secret: [POSTGRES_PASSWORD]
+    volumes: [/var/lib/epd/volumes/blog-db:/var/lib/postgresql/data]
+    ports: ["127.0.0.1:5432:5432"]
+
+hooks:
+  pre_deploy: ./bin/test
+  post_deploy: ./bin/notify
+
+strategy: rolling       # rolling (one host at a time) | parallel
+keep_releases: 5
+```
+
+Run `epd config` to see every default filled in, and `epd config --traefik` to
+see the exact proxy configuration epd will write.
+
+### The short form
+
+For a single service you can skip the `servers:` block entirely:
+
+```yaml
+name: site
+hosts: [203.0.113.10]
+port: 3000
+domains: [example.com]
+proxy:
+  email: me@example.com
+```
+
+### Routes: several sites, paths and ports
+
+`domains:` is shorthand. `routes:` gives you the rest — this is the part Kamal
+cannot express:
+
+```yaml
+servers:
+  web:
+    hosts: [203.0.113.10]
+    port: 3000
+    routes:
+      - host: example.com                 # → :3000
+      - host: api.example.com
+        port: 8080                        # a different port, same container
+      - host: example.com
+        path: /admin
+        port: 4000
+        strip_path: true                  # /admin/x reaches the app as /x
+        basic_auth: ["admin:$apr1$…"]
+      - host: www.example.com
+        redirect: https://example.com
+      - host: "*.example.com"             # wildcard (needs a DNS challenge)
+        priority: 1
+      - host: internal.example.com
+        entrypoint: private               # a non-standard port, see below
+        ssl: false
+      - host: example.com
+        path: /ws
+        sticky: true                      # cookie-pinned load balancing
+```
+
+Extra entrypoints are ports Traefik listens on, declared once and shared by
+every app on the server:
+
+```yaml
+proxy:
+  entrypoints:
+    web: 80
+    websecure: 443
+    private: 8443
+```
+
+### Environment and secrets
+
+`env.clear` is written into the config; `env.secret` lists variable *names*
+whose values are read from your shell or a `.env` file at deploy time and
+written to the server as a `0600` file. Secrets never end up in the repo, in a
+`docker inspect`, or in your shell history.
+
+`.env`, `.env.local` and `.env.<destination>` next to `epd.yml` are loaded
+automatically. Real environment variables always win.
+
+### Destinations
+
+```bash
+epd deploy -d staging
+```
+
+merges `epd.staging.yml` over `epd.yml` and loads `.env.staging`. Useful for a
+staging fleet, a different domain, or fewer replicas.
+
+---
+
+## Multiple servers, load balancing and failover
+
+Each server runs a Traefik instance and its own replicas. Two levels of
+balancing are available:
+
+**Per host (default).** Traefik balances across the replicas on its own machine
+and drops any replica that fails its health check. Spread traffic across
+machines with round-robin DNS or a load balancer in front.
+
+**Across hosts (`proxy.cross_host: true`).** Every server's proxy balances
+across *every* server's replicas. If one machine's app dies — or the whole
+machine does — the others keep serving its share, so DNS round-robin no longer
+sends a fraction of visitors to a dead box.
+
+```yaml
+proxy:
+  cross_host: true
+  private_ips:            # optional: keep the traffic on a private network
+    203.0.113.10: 10.0.0.10
+    203.0.113.11: 10.0.0.11
+```
+
+With `cross_host` the app port is published on each host (bound to the private
+address when you set one), so replicas can be reached from the other machines.
+Firewall that port to your servers.
+
+Deploys roll one host at a time by default, so the fleet keeps serving
+throughout. `strategy: parallel` deploys everywhere at once when you would
+rather have it over with.
+
+### Certificates on several machines
+
+Each server gets its own certificate. With the HTTP challenge and round-robin
+DNS, a challenge request can land on a machine that is not the one asking, and
+the first attempt may fail before a retry succeeds. For more than one machine
+use the DNS challenge:
+
+```yaml
+proxy:
+  challenge: dns
+  dns_provider: cloudflare
+  dns_env: [CF_DNS_API_TOKEN]
+```
+
+The listed variables are read from your environment and passed to Traefik.
+
+---
+
+## Without Docker: process mode
+
+```yaml
+name: site
+mode: process
+
+process:
+  install: bun install --frozen-lockfile
+  build: bun run build
+  start: bun run start        # each replica gets a unique $PORT
+  exclude: [".git", "node_modules", ".env"]
+  source: rsync               # or "git" to upload a clean archive of HEAD
+
+servers:
+  web:
+    hosts: [203.0.113.10]
+    replicas: 2
+    port: 3000
+    domains: [example.com]
+```
+
+`epd setup` installs rsync, Node (pm2 needs it), Bun and pm2, and downloads the
+Traefik binary — the server never needs Docker. Deploys rsync the project into
+`/var/lib/epd/apps/<app>/releases/<version>`, run your install and build
+commands there, start the new replicas under pm2 on the other slot, health check
+them, switch the routes and then delete the old slot.
+
+Your start command is run as-is with `PORT`, `EPD_REPLICA`, `EPD_VERSION` and
+your `env` entries set. Two replicas means two processes on two ports, balanced
+by Traefik.
+
+Everything else works the same: `epd status`, `epd logs`, `epd rollback`,
+`epd exec`. Accessories are the one exception — they are always containers, so
+they need Docker on their host.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `epd init` | Create an `epd.yml` (and a starter Dockerfile) |
+| `epd setup` | Install what the servers need, start the proxy, deploy |
+| `epd deploy` | Build and deploy; `--no-build` to reuse a version |
+| `epd redeploy` | Restart the current version everywhere |
+| `epd rollback [version]` | Back to the previous version; `--list` to see them |
+| `epd status` | Every replica, slot, version, accessories and the proxy state |
+| `epd logs -f` | Logs from every replica, prefixed by name (supports `--accessory`) |
+| `epd exec -- <cmd>` | Run a command with the app's image and environment (supports `--accessory`) |
+| `epd shell` | A shell inside a container or accessory that is serving traffic |
+| `epd proxy status\|reboot\|logs\|routes\|remove` | The shared proxy |
+| `epd config` | The resolved configuration; `--traefik` for the proxy files |
+| `epd docker-command` | Print the exact `docker run` (or pm2) commands epd uses (including accessories) |
+| `epd lock status\|release` | The deploy lock |
+| `epd remove` | Stop this app and delete its files from the servers |
+
+Global flags: `-c/--config`, `-d/--destination`, `-v/--verbose`.
+
+### Generating the docker command
+
+```bash
+epd docker-command --service web --slot blue
+```
+
+prints the exact, copy-pasteable `docker run` for each replica plus the proxy
+container — useful to check what epd is doing, to run something by hand, or to
+lift the command into another tool. In process mode it prints the pm2
+equivalent.
+
+---
+
+## How it fits together on a server
+
+```
+/var/lib/epd/
+  apps/<app>/            state.json, env files, releases (process mode)
+  proxy/
+    traefik.yml          static config, merged from every app on the host
+    dynamic/<app>.yml    one routing file per app — this is what makes
+    acme/                multiple sites on one machine painless
+  ports/                 the port block each app reserved
+```
+
+Containers are named `epd-<app>-<service>-<slot>-<replica>` and labelled with
+the app, service, slot and version, so everything epd owns is easy to find and
+nothing else on the machine is touched.
+
+---
+
+## Troubleshooting
+
+**`epd status` says a host is unreachable.** epd uses your `ssh` binary and
+config. Check with `ssh -p <port> <user>@<host>` first; add `ssh.key` if you
+have many keys loaded.
+
+**The health check times out.** The new replicas started but did not answer.
+`epd logs --service web` shows why. The old version is still serving — nothing
+was switched. Point `healthcheck.path` at something cheap that returns 2xx, or
+set `healthcheck: false` for a service that is not an HTTP server.
+
+**A certificate is not issued.** `epd proxy logs` shows the ACME exchange. The
+domain must resolve to the server and port 80 must be reachable. On multiple
+machines, use the DNS challenge.
+
+**`ports NNNNN-NNNNN are already reserved`.** Two apps hashed to the same port
+block. Set `port_base:` in one of them to any free multiple of 256.
+
+**A deploy was interrupted and now everything is locked.** `epd lock release`.
+
+---
+
+## Tests
+
+```bash
+bun test                  # config, routing, port allocation, health probes
+./test/e2e/run.sh         # real deploy over ssh: docker mode, two apps, rollback
+./test/e2e/process.sh     # real deploy over ssh: process mode, pm2, no docker
+```
+
+The end-to-end tests build a throwaway "server" container running sshd and
+deploy to it for real — including a zero-downtime check that fails if any
+request drops during a deploy.
+
+## License
+
+MIT

package/bin/epd.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env bun
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distBundle = join(__dirname, "..", "dist", "cli.js");
+
+if (existsSync(distBundle)) {
+  await import(distBundle);
+} else {
+  await import("../src/cli.ts");
+}