diff --git a/DEPLOY.md b/DEPLOY.md index 6ea0f5b6..a11b2957 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -14,8 +14,8 @@ small Alpine runtime) and published to GHCR: Or build it yourself with `docker build -t calnode .`. -This guide covers a standalone binary, a generic Docker deploy and a step-by-step **Railway** deploy -(the current reference host). +This guide covers a standalone binary, a **nibrun** deploy, a generic Docker deploy +and a step-by-step **Railway** deploy (the current reference host). ## Standalone binary @@ -51,6 +51,72 @@ backup method. The email, calendar and other integration settings below still ap --- +## nibrun + +[nibrun](https://nibrun.com) runs the standalone Linux amd64 binary in an isolated +microVM with HTTPS and a persistent volume. No Docker image or local build is needed. + +1. Generate two separate secrets: + + ```bash + openssl rand -hex 32 # CALNODE_ENCRYPTION_KEY + openssl rand -hex 32 # CALNODE_RECOVERY_SECRET + ``` + + Save both securely and keep the recovery secret separately. Reuse them on + redeploys; changing the encryption key requires Calnode's key-rotation procedure. +2. Click **Deploy on nibrun** in the [README](README.md#deploy-for-real), sign in to + nibrun, and paste the secrets into the corresponding fields. The button pins + **v0.11.2** and its SHA-256 checksum and prefills: + + | Setting | Value | + |---|---| + | HTTP port | `3000` (also supplied to the binary as `PORT`) | + | `BASE_URL` | `https://${NIBRUN_HOSTNAME}` | + | `DATABASE_URL` | `sqlite://${NIBRUN_DATA_DIR}/calnode.db` | + | `DATA_DIR` | `${NIBRUN_DATA_DIR}` | + | `TRUSTED_PROXY_CIDRS` | `127.0.0.1` | + + nibrun expands the runtime references when starting the binary. The database + and uploaded assets live under `/app/data`, which survives redeploys. +3. Deploy, open the returned HTTPS URL, and complete first-run setup immediately + to claim the owner account. On a fresh database, the first visitor can claim it. +4. Configure email and calendar integrations in Calnode's Settings, then create + an event type and availability. The integration instructions below still apply. + +For a custom domain, add it in nibrun, update `BASE_URL` to the full HTTPS URL, +and update the registered OAuth redirect URIs to match. + +`TRUSTED_PROXY_CIDRS` trusts nibrun's loopback Caddy proxy, so Calnode reads its +`X-Forwarded-For` header instead of putting every visitor in one rate-limit bucket. +The current nibrun proxy replaces the incoming forwarded chain with the Cloudflare +edge address: visitors routed through the same edge address still share rate +limits. Adding Cloudflare CIDRs to Calnode's trust list alone cannot recover the +visitor address; the proxy would also need to preserve that chain. + +The standalone binary does **not** include Litestream or the container entrypoint; +setting `LITESTREAM_REPLICA_URL` alone does not enable database backup or restore. +For an on-demand backup, use **Export** in nibrun's dashboard, or run this with the +`nib` CLI installed and signed in: + +```bash +nib apps export ./calnode-backup.tar.gz --app calnode +``` + +Replace `calnode` with the app name you chose. The archive contains `data/` +(including the SQLite database and uploaded assets), the deployed binary, and a +`.env` with its environment variables. Keep it private and store a copy outside +nibrun: the bundle includes credentials. To restore, extract the archive and +deploy its binary with `data/` as initial data and the original environment +variables from `.env`, including the encryption key. Exports are point-in-time +backups; they do not provide Litestream's continuous replication or automatic restore. + +nibrun suspends idle apps and wakes them on an incoming request. Calnode's +in-process reminder, webhook-retry and calendar-reconciliation workers pause while +the app is suspended, so scheduled background work can be delayed until it wakes. + +--- + ## 1. Configuration (environment variables) | Variable | Required | Default | Notes | diff --git a/README.md b/README.md index 65102b39..c6701b88 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,11 @@ include standalone Linux amd64 and arm64 archives, each containing the static [running the standalone binary](DEPLOY.md#standalone-binary) for setup and backup differences from the container. +**On nibrun:** deploy the standalone binary with HTTPS and persistent storage. +See the [nibrun setup guide](DEPLOY.md#nibrun) for secrets and first-run setup. + +[![Deploy on nibrun](https://nibrun.com/button.svg)](https://app.nibrun.com/deploy?name=calnode&binary=https%3A%2F%2Fgithub.com%2FCalnode%2Fcalnode%2Freleases%2Fdownload%2Fv0.11.2%2Fcalnode_0.11.2_linux_amd64.tar.gz&sha256=dc69723becc79ab23125e6e8ff2c030c8fc268b54ec5de4313684702c7b2c03b&port=3000&env=%5B%22BASE_URL%3Dhttps%3A%2F%2F%24%7BNIBRUN_HOSTNAME%7D%22%2C%22DATABASE_URL%3Dsqlite%3A%2F%2F%24%7BNIBRUN_DATA_DIR%7D%2Fcalnode.db%22%2C%22DATA_DIR%3D%24%7BNIBRUN_DATA_DIR%7D%22%2C%22TRUSTED_PROXY_CIDRS%3D127.0.0.1%22%2C%22CALNODE_ENCRYPTION_KEY%22%2C%22CALNODE_RECOVERY_SECRET%22%5D&minimal=true) + ```bash docker run -d -p 3000:3000 \ -e BASE_URL=https://booking.example.com \