jonnyn/warmbox
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update .env.example with new PUBLIC_BASE_URL, remove unused docker-compose.npm.yml and Caddyfile, and adjust docker-compose.yml to simplify network configuration. Revise deployment documentation to reflect changes in setup and clarify Nginx Proxy Manager integration.

Browse source
This commit is contained in:
Jonny Nguyen 2026-06-26 13:00:32 -07:00
parent f98cc61cf7
commit ac09760771
7 changed files with 149 additions and 262 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.env.example
View file

@ -13,7 +13,7 @@ ENCRYPTION_KEY=""
API_KEY="" API_KEY=""
# Public URL users and OAuth providers see (no trailing slash) # Public URL users and OAuth providers see (no trailing slash)
PUBLIC_BASE_URL="https://warmbox.yourdomain.com" PUBLIC_BASE_URL="https://warmbox.jonnyn.com"
PORT=3000 PORT=3000
NODE_ENV=production NODE_ENV=production

7
deploy/Caddyfile
View file

@ -1,7 +0,0 @@
# Replace warmbox.yourdomain.com with your hostname (e.g. warmbox.jonnyn.com).
# Only use this profile if Nginx Proxy Manager is NOT already bound to 80/443.
warmbox.jonnyn.com {
encode gzip
reverse_proxy warmbox:3000
}

14
docker-compose.npm.yml
View file

@ -1,14 +0,0 @@
# Use with: docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --build
#
# Attaches Warmbox to your existing Nginx Proxy Manager network so NPM can proxy
# warmbox.jonnyn.com → http://warmbox:3000
services:
warmbox:
networks:
- warmbox_internal
- npm_network
networks:
npm_network:
external: true

45
docker-compose.yml
View file

@ -2,6 +2,7 @@ services:
warmbox: warmbox:
build: . build: .
image: warmbox:local image: warmbox:local
container_name: warmbox
restart: unless-stopped restart: unless-stopped
env_file: .env env_file: .env
environment: environment:
@ -9,54 +10,18 @@ services:
NODE_ENV: production NODE_ENV: production
volumes: volumes:
- warmbox-data:/data - warmbox-data:/data
# No host ports — reach Warmbox via Docker network only (NPM or Cloudflare Tunnel). # No host ports — NPM reaches this container on npm_network at warmbox:3000
# For LAN debugging only, temporarily add: ports: ["127.0.0.1:3001:3000"]
healthcheck: healthcheck:
test: ['CMD', 'node', '-e', "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] test: ['CMD', 'node', '-e', "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s interval: 30s
timeout: 5s timeout: 5s
retries: 3 retries: 3
start_period: 40s start_period: 40s
networks:
- warmbox_internal
# Cloudflare Tunnel connector — shares warmbox_internal with the app.
cloudflared:
profiles: [cloudflare]
image: cloudflare/cloudflared:latest
restart: unless-stopped
depends_on:
warmbox:
condition: service_healthy
command: tunnel run
environment:
TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN}
networks:
- warmbox_internal
# Standalone Caddy — only if you do NOT already run Nginx Proxy Manager on 80/443.
caddy:
profiles: [caddy]
image: caddy:2-alpine
restart: unless-stopped
depends_on:
warmbox:
condition: service_healthy
ports:
- '80:80'
- '443:443'
volumes:
- ./deploy/Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data
- caddy-config:/config
networks:
- warmbox_internal
volumes: volumes:
warmbox-data: warmbox-data:
caddy-data:
caddy-config:
networks: networks:
warmbox_internal: default:
name: warmbox_internal external: true
name: npm_network

337
docs/deploy-ubuntu-docker.md
View file

@ -1,146 +1,134 @@
# Deploy Warmbox on Ubuntu (Docker) # Deploy Warmbox with Nginx Proxy Manager (Docker)
Warmbox is a **long-running worker** (cron dispatcher, rescuer, SMTP/IMAP). It needs: Warmbox runs as one container on your existing **`npm_network`**. Nginx Proxy Manager (NPM) terminates HTTPS and forwards to `http://warmbox:3000`.
- A persistent database (SQLite volume) ```text
- Outbound SMTP/IMAP from the server Internet → warmbox.jonnyn.com (DNS) → NPM :443 → warmbox:3000 (Docker network)
- A public HTTPS URL for the dashboard and OAuth callbacks ```
**Not suitable:** Netlify, GitHub Pages, Vercel — no background jobs, no SQLite, no mail sockets. No host port is published. Warmbox can run alongside `homepage` on host port 3000 — they do not conflict.
--- ---
## Your setup (`warmbox.jonnyn.com`) ## Prerequisites
You already have: - Ubuntu server with Docker + Compose v2
- [Nginx Proxy Manager](https://nginxproxymanager.com/) already running on Docker network **`npm_network`**
- DNS **A** record: `warmbox.jonnyn.com` → your home public IP
- Router forwards **80** and **443** to NPM (if not already)
- DNS **A** record → home public IP Confirm NPM’s network name:
- **Nginx Proxy Manager** (NPM) on Docker network `npm_network`
**Recommended for you: Option B — Nginx Proxy Manager** (simplest; reuses what you have).
Use **Option A — Cloudflare Tunnel** only if you want HTTPS without opening ports 80/443, or if your ISP blocks inbound traffic.
Do **not** run Caddy (Option C) alongside NPM — both want ports 80 and 443.
---
## 1. Prepare the server
```bash ```bash
cd ~/warmbox # or wherever you cloned the repo docker network ls | grep npm
docker inspect <npm-container-name> --format '{{json .NetworkSettings.Networks}}' | jq
```
If your network is not `npm_network`, edit `networks.default.name` in `docker-compose.yml`.
---
## 1. Clone and configure
```bash
cd /srv/docker-configs/warmbox # or your path
git pull # get latest docker-compose.yml
cp .env.example .env cp .env.example .env
nano .env nano .env
``` ```
Required in `.env`: Required variables:
```bash ```bash
ENCRYPTION_KEY=<64 hex chars — openssl rand -hex 32> ENCRYPTION_KEY=<openssl rand -hex 32> # never change after first deploy
API_KEY=<openssl rand -hex 24> API_KEY=<openssl rand -hex 24> # dashboard login
PUBLIC_BASE_URL=https://warmbox.jonnyn.com PUBLIC_BASE_URL=https://warmbox.jonnyn.com
AI_API_KEY=sk-or-v1-... AI_API_KEY=sk-or-v1-...
``` ```
Keep `ENCRYPTION_KEY` forever. If migrating from your Mac, copy the same key and `prisma/dev.db`. **Migrating from your Mac:** use the **same** `ENCRYPTION_KEY` and copy `prisma/dev.db` (see §6).
--- ---
## 2. Fix: “port 3000 already allocated” ## 2. Start Warmbox
Warmbox listens on **port 3000 inside its container**. That does **not** conflict with `homepage` using host port `3000` — unless you publish Warmbox to the host with a `ports:` mapping.
**NPM and Cloudflare Tunnel only need Docker network access** (`warmbox:3000`). No host port is required.
### Verify your compose file on the server
```bash ```bash
cd /srv/docker-configs/warmbox cd /srv/docker-configs/warmbox
grep -n ports docker-compose.yml docker-compose.npm.yml 2>/dev/null
docker compose -f docker-compose.yml -f docker-compose.npm.yml config | grep -A2 published
```
- **Correct:** no `published` / `ports` for the `warmbox` service (empty grep for warmbox ports). # Stop any old stack (including previous compose overrides)
- **Wrong:** lines like `"3000:3000"` or `"127.0.0.1:3000:3000"` under `warmbox` — **delete the entire `ports:` block** for that service. docker compose down
Pull the latest repo (or remove `ports:` manually), then: # Build and start — joins npm_network automatically
docker compose up -d --build
```bash
docker compose -f docker-compose.yml -f docker-compose.npm.yml down
docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --build
```
### Optional: direct LAN access on a different host port
Only if you want to hit Warmbox without NPM (debugging). This uses host **3001**, not 3000:
```yaml
ports:
- "127.0.0.1:3001:3000"
```
NPM still uses forward port **3000** (container port), not 3001.
### Find what uses host port 3000
```bash
docker ps --format '{{.Names}} {{.Ports}}' | grep '0.0.0.0:3000'
```
In your case `homepage` owns host 3000 — leave it alone; Warmbox does not need that port.
---
## Option B — Nginx Proxy Manager (recommended for your home server)
Traffic path:
```text
Internet → warmbox.jonnyn.com (DNS A → home IP) → NPM :443 → warmbox:3000 (Docker)
```
### Step 1 — Start Warmbox on `npm_network`
```bash
docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --build
``` ```
Verify: Verify:
```bash ```bash
docker compose -f docker-compose.yml -f docker-compose.npm.yml ps docker compose ps
docker compose -f docker-compose.yml -f docker-compose.npm.yml logs -f warmbox docker compose logs -f warmbox
curl -s http://warmbox:3000/health # run from any container on npm_network, or skip
``` ```
### Step 2 — NPM proxy host Warmbox should be **healthy**. Check it is on `npm_network`:
In Nginx Proxy Manager UI: ```bash
docker inspect warmbox --format '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}'
# should include: npm_network
```
| Field | Value | Test from another container on the same network (e.g. NPM):
|--------|--------|
```bash
docker exec -it <npm-app-container> wget -qO- http://warmbox:3000/health
# expect: {"status":"ok"}
```
---
## 3. Nginx Proxy Manager — proxy host
Open NPM UI (usually `http://<server-ip>:81`).
**Hosts → Proxy Hosts → Add Proxy Host**
| Tab / field | Value |
|-------------|--------|
| Domain names | `warmbox.jonnyn.com` | | Domain names | `warmbox.jonnyn.com` |
| Scheme | `http` | | Scheme | `http` |
| Forward hostname / IP | `warmbox` | | Forward hostname / IP | `warmbox` |
| Forward port | `3000` (container port — not your host port 3000 used by homepage) | | Forward port | `3000` |
| Cache assets | off | | Cache assets | off |
| Block common exploits | on | | Block common exploits | on |
| Websockets support | on | | Websockets support | on |
**SSL** tab: **SSL** tab:
- Request a new SSL Certificate (Let's Encrypt) - SSL Certificate: Request a new Let's Encrypt certificate
- Force SSL + HTTP/2 - Force SSL: on
- HTTP/2: on
If you use **Cloudflare orange cloud** (proxied) on the A record, set Cloudflare SSL mode to **Full** or **Full (strict)** so NPM’s certificate works. If Cloudflare proxies your A record (orange cloud), set Cloudflare SSL mode to **Full** or **Full (strict)**.
### Step 3 — Login Save, then test:
```bash
curl -s https://warmbox.jonnyn.com/health
```
---
## 4. Dashboard login
1. Open `https://warmbox.jonnyn.com` 1. Open `https://warmbox.jonnyn.com`
2. API key = your `API_KEY` from `.env` 2. Enter `API_KEY` from `.env`
3. Leave **Base URL** blank 3. Leave **Base URL** empty (same origin in production)
### Step 4 — OAuth redirect URIs ---
## 5. OAuth redirect URIs
Update in Google Cloud / Azure if you use these integrations:
| Integration | Redirect URI | | Integration | Redirect URI |
|-------------|----------------| |-------------|----------------|
@ -149,116 +137,35 @@ If you use **Cloudflare orange cloud** (proxied) on the A record, set Cloudflare
--- ---
## Option A — Cloudflare Tunnel ## 6. Migrate local database (optional)
Use this if you prefer **no inbound ports** on your router (tunnel only).
Traffic path:
```text
Browser → Cloudflare edge → cloudflared (Docker) → warmbox:3000
```
### Important DNS note
For tunnel-only access, let the **tunnel** own the hostname. In Cloudflare Zero Trust → your tunnel → **Public Hostname**:
| Field | Value |
|--------|--------|
| Subdomain | `warmbox` |
| Domain | `jonnyn.com` |
| Type | HTTP |
| URL | `warmbox:3000` |
Cloudflare usually creates a CNAME for you. You can **remove the A record** for `warmbox` if everything goes through the tunnel (avoids split routing).
### Step 1 — `.env`
```bash ```bash
CLOUDFLARE_TUNNEL_TOKEN=eyJh... # from Zero Trust → Tunnels → your tunnel → Docker install # On your Mac
PUBLIC_BASE_URL=https://warmbox.jonnyn.com scp prisma/dev.db jonnyn@burke:/tmp/warmbox.db
```
### Step 2 — Start (no NPM override file) # On server
cd /srv/docker-configs/warmbox
```bash docker compose down
docker compose --profile cloudflare up -d --build
```
`cloudflared` and `warmbox` share the `warmbox_internal` network — hostname `warmbox` resolves inside that network.
### Step 3 — Verify
```bash
docker compose --profile cloudflare ps
docker compose --profile cloudflare logs -f cloudflared
docker compose --profile cloudflare logs -f warmbox
curl -s https://warmbox.jonnyn.com/health
```
### Tunnel + NPM together?
Pick **one** public entry for `warmbox.jonnyn.com`:
- **NPM only:** A record → home IP, no tunnel hostname for the same subdomain.
- **Tunnel only:** tunnel hostname, no A record to home IP for that subdomain.
Running both for the same hostname causes confusing SSL or routing issues.
---
## Option C — Caddy (standalone, no NPM)
Only if NPM is **not** using 80/443 on this host.
1. Edit `deploy/Caddyfile` — set `warmbox.jonnyn.com`
2. DNS A record → home public IP; forward router 80/443 to the server
3. Start:
```bash
docker compose --profile caddy up -d --build
```
**Skip this** if Nginx Proxy Manager is already on the server.
---
## Migrate local database (optional)
```bash
# Mac
scp prisma/dev.db user@home-server:/tmp/warmbox.db
# Server — stack stopped
docker compose -f docker-compose.yml -f docker-compose.npm.yml down
docker run --rm -v warmbox_warmbox-data:/data -v /tmp:/backup alpine \ docker run --rm -v warmbox_warmbox-data:/data -v /tmp:/backup alpine \
cp /backup/warmbox.db /data/warmbox.db cp /backup/warmbox.db /data/warmbox.db
docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d docker compose up -d
``` ```
Use the **same** `ENCRYPTION_KEY` as on your Mac. Use the same `ENCRYPTION_KEY` as on your Mac.
--- ---
## Day-to-day commands ## 7. Day-to-day commands
**NPM deployment:**
```bash ```bash
docker compose -f docker-compose.yml -f docker-compose.npm.yml logs -f warmbox cd /srv/docker-configs/warmbox
docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --build
```
**Cloudflare deployment:** docker compose logs -f warmbox # live logs
docker compose up -d --build # rebuild after git pull
docker compose down # stop
docker compose restart warmbox # restart app only
```bash # Backup SQLite
docker compose --profile cloudflare logs -f warmbox
docker compose --profile cloudflare up -d --build
```
**Backup:**
```bash
docker compose exec warmbox sh -c 'cp /data/warmbox.db /data/warmbox-$(date +%F).db' docker compose exec warmbox sh -c 'cp /data/warmbox.db /data/warmbox-$(date +%F).db'
``` ```
@ -266,13 +173,51 @@ docker compose exec warmbox sh -c 'cp /data/warmbox.db /data/warmbox-$(date +%F)
## Troubleshooting ## Troubleshooting
| Symptom | Fix | ### `port 3000 already allocated`
|---------|-----|
| `port 3000 already allocated` | Use updated compose (no host ports); `docker compose down`; find conflict with `docker ps \| grep 3000` | Your `docker-compose.yml` must **not** have a `ports:` section under `warmbox`:
| NPM 502 Bad Gateway | Warmbox not on `npm_network`; wrong forward host (`warmbox` not `localhost`); check `docker compose logs warmbox` |
| Tunnel 502 / error | Public hostname URL must be `http://warmbox:3000`; both containers on `warmbox_internal`; check `logs cloudflared` | ```bash
| Login fails | `API_KEY` in `.env` must match login; restart after `.env` change | grep ports docker-compose.yml
| OAuth redirect error | `PUBLIC_BASE_URL=https://warmbox.jonnyn.com` exactly; update Google/Microsoft redirect URIs | # should return nothing (or only comments)
| SSL errors with Cloudflare proxy | Cloudflare SSL mode **Full** or **Full (strict)** when NPM terminates TLS | ```
Warmbox uses port 3000 **inside** the container only. `homepage` on host `0.0.0.0:3000` is unrelated.
### NPM 502 Bad Gateway
1. Warmbox running and healthy: `docker compose ps`
2. On `npm_network`: `docker inspect warmbox --format '{{json .NetworkSettings.Networks}}'`
3. NPM forward host is `warmbox` (not `localhost`, not `127.0.0.1`)
4. NPM forward port is `3000`
5. Logs: `docker compose logs warmbox`
### `network npm_network not found`
Create it or fix the name to match NPM:
```bash
docker network ls
# edit docker-compose.yml → networks.default.name
```
### Login fails
- `API_KEY` in `.env` must match what you type
- Restart after `.env` change: `docker compose up -d --force-recreate`
### Container unhealthy
```bash
docker compose logs warmbox
```
Common causes: missing `ENCRYPTION_KEY`, bad `DATABASE_URL`, migration error.
---
## Why only `npm_network`?
NPM and Warmbox must share a Docker network so NPM can resolve the hostname `warmbox`. A separate `warmbox_internal` network is unnecessary for this setup — one external network is enough.
See also [self-host-hardening.md](./self-host-hardening.md). See also [self-host-hardening.md](./self-host-hardening.md).

4
docs/self-host-hardening.md
View file

@ -21,9 +21,9 @@ npm run dev # API :3000, dashboard :5173
npm run build && npm run start npm run build && npm run start
``` ```
### Run on Ubuntu / VPS (Docker) ### Run on Ubuntu / VPS (Docker + Nginx Proxy Manager)
For a **30-day live test** without keeping your laptop on, see **[deploy-ubuntu-docker.md](./deploy-ubuntu-docker.md)** (Docker Compose + Cloudflare Tunnel or Caddy). For a **30-day live test** without keeping your laptop on, see **[deploy-ubuntu-docker.md](./deploy-ubuntu-docker.md)**.
## Operator workflows (no curl required) ## Operator workflows (no curl required)

2
package.json
View file

@ -12,8 +12,6 @@
"build": "npm run build -w @warmbox/shared && npm run build -w @warmbox/api && npm run build -w @warmbox/web", "build": "npm run build -w @warmbox/shared && npm run build -w @warmbox/api && npm run build -w @warmbox/web",
"start": "npm run start -w @warmbox/api", "start": "npm run start -w @warmbox/api",
"docker:up": "docker compose up -d --build", "docker:up": "docker compose up -d --build",
"docker:up:npm": "docker compose -f docker-compose.yml -f docker-compose.npm.yml up -d --build",
"docker:up:cloudflare": "docker compose --profile cloudflare up -d --build",
"docker:logs": "docker compose logs -f warmbox", "docker:logs": "docker compose logs -f warmbox",
"db:migrate": "prisma migrate dev", "db:migrate": "prisma migrate dev",
"db:generate": "prisma generate", "db:generate": "prisma generate",