Skip to content

Commit a4b1ed6

Browse files
authored
Merge pull request #49 from rebase-network/dev
feat(skills): add deployment runbooks
2 parents 6d1e937 + b6af60d commit a4b1ed6

9 files changed

Lines changed: 449 additions & 18 deletions

File tree

‎apps/api/src/lib/asset-storage.ts‎

Lines changed: 85 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
import { execFile } from 'node:child_process';
22
import { createHash, randomUUID } from 'node:crypto';
3+
import { existsSync } from 'node:fs';
34
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
45
import { tmpdir } from 'node:os';
5-
import { extname, join } from 'node:path';
6+
import { dirname, extname, join } from 'node:path';
67
import { promisify } from 'node:util';
78

89
import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
@@ -148,19 +149,94 @@ const getS3Client = () => {
148149
return s3Client;
149150
};
150151

152+
const findWorkspaceBinary = (binaryName: string) => {
153+
let currentDir = process.cwd();
154+
155+
while (true) {
156+
const candidate = join(currentDir, 'node_modules', '.bin', binaryName);
157+
if (existsSync(candidate)) {
158+
return candidate;
159+
}
160+
161+
const parentDir = dirname(currentDir);
162+
if (parentDir === currentDir) {
163+
break;
164+
}
165+
166+
currentDir = parentDir;
167+
}
168+
169+
return binaryName;
170+
};
171+
172+
const getWranglerExecutable = () => {
173+
const configured = process.env.WRANGLER_BIN?.trim();
174+
if (configured) {
175+
return configured;
176+
}
177+
178+
return findWorkspaceBinary('wrangler');
179+
};
180+
181+
const toTrimmedOutput = (value: unknown) => {
182+
if (typeof value !== 'string') {
183+
return undefined;
184+
}
185+
186+
const normalized = value.trim();
187+
if (!normalized) {
188+
return undefined;
189+
}
190+
191+
return normalized.slice(0, 400);
192+
};
193+
194+
const runWrangler = async (args: string[]) => {
195+
const env = getEnv();
196+
const executable = getWranglerExecutable();
197+
198+
try {
199+
return await execFileAsync(executable, args, {
200+
env: {
201+
...process.env,
202+
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
203+
},
204+
});
205+
} catch (error) {
206+
if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
207+
throw serviceUnavailable('Wrangler CLI is not available for R2 uploads', {
208+
hint: 'set WRANGLER_BIN or expose node_modules/.bin on PATH',
209+
executable,
210+
});
211+
}
212+
213+
const details: Record<string, unknown> = {
214+
hint: 'check the mounted Wrangler profile, CLI login state, and bucket permissions',
215+
executable,
216+
reason: error instanceof Error ? error.message : String(error),
217+
};
218+
const stderr = typeof error === 'object' && error !== null && 'stderr' in error ? toTrimmedOutput(error.stderr) : undefined;
219+
const stdout = typeof error === 'object' && error !== null && 'stdout' in error ? toTrimmedOutput(error.stdout) : undefined;
220+
if (stderr) {
221+
details.stderr = stderr;
222+
}
223+
if (stdout) {
224+
details.stdout = stdout;
225+
}
226+
227+
throw serviceUnavailable('Wrangler CLI failed while accessing R2', {
228+
...details,
229+
});
230+
}
231+
};
232+
151233
const getWranglerPublicBaseUrl = async (bucket: string) => {
152234
const cached = wranglerDevUrlCache.get(bucket);
153235
if (cached) {
154236
return cached;
155237
}
156238

157-
const env = getEnv();
158-
const result = await execFileAsync('wrangler', ['r2', 'bucket', 'dev-url', 'get', bucket], {
159-
env: {
160-
...process.env,
161-
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
162-
},
163-
});
239+
const result = await runWrangler(['r2', 'bucket', 'dev-url', 'get', bucket]);
164240

165241
const output = `${result.stdout}\n${result.stderr}`;
166242
const match = output.match(/https:\/\/[^\s]+/);
@@ -212,16 +288,7 @@ const uploadWithWrangler = async (objectKey: string, body: Buffer, mimeType: str
212288

213289
try {
214290
await writeFile(tempFile, body);
215-
await execFileAsync(
216-
'wrangler',
217-
['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType],
218-
{
219-
env: {
220-
...process.env,
221-
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
222-
},
223-
},
224-
);
291+
await runWrangler(['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType]);
225292
} finally {
226293
await rm(tempDir, { recursive: true, force: true });
227294
}

‎skills/rebase-api-rollout/SKILL.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
name: rebase-api-rollout
3+
description: Deploy and operate the Rebase backend server stack on `rebase@101.33.75.240`. Use when releasing or debugging `apps/api`, PostgreSQL, `cloudflared`, server env files, Docker Compose rollout, readiness checks, admin bootstrap, database backups, or the end-to-end server side of the Rebase production release.
4+
---
5+
6+
# Rebase API Rollout
7+
8+
## Overview
9+
10+
Use this skill for the server-managed half of the Rebase production stack. It centers on `ops/manage.sh`, the Docker Compose topology in `infra/production/docker-compose.yml`, and the production config registry in `docs/production-config.md`.
11+
12+
## Standard Rollout
13+
14+
1. Keep the code on `dev` until it is validated.
15+
2. Validate release readiness locally when needed:
16+
- `pnpm deploy:server:config`
17+
- any targeted API checks for the touched area
18+
3. Use `./ops/manage.sh check` before a remote rollout.
19+
4. Use `./ops/manage.sh deploy api` for API-only changes.
20+
5. Use `./ops/manage.sh deploy stack` when API, Postgres, or `cloudflared` changes require the full stack.
21+
6. Verify with:
22+
- `./ops/manage.sh ps`
23+
- `./ops/manage.sh health`
24+
- `./ops/manage.sh ready`
25+
- `./ops/manage.sh logs api 200`
26+
7. Run targeted DB or bootstrap commands only when the task requires them.
27+
28+
## Current Production Topology
29+
30+
- host: `rebase@101.33.75.240`
31+
- repo dir: `/home/rebase/rebase.network`
32+
- compose file: `infra/production/docker-compose.yml`
33+
- env file: `infra/production/server.env`
34+
- API service: `api`
35+
- DB service: `postgres`
36+
- tunnel service: `cloudflared`
37+
- public API hostname: `https://api.rebase.network`
38+
39+
Use `references/runbook.md` for the exact command set and `references/troubleshooting.md` for the known failure modes.
40+
41+
## When To Read References
42+
43+
- Read `references/runbook.md` before performing a routine rollout, restart, log inspection, DB query, backup, or bootstrap action.
44+
- Read `references/troubleshooting.md` when health checks fail, compose services do not come up, the tunnel is broken, the env file is missing, or the DB needs verification.
45+
46+
## Guardrails
47+
48+
- Prefer `ops/manage.sh` over ad-hoc SSH commands.
49+
- Keep PostgreSQL private to the server and compose network; do not expose it publicly.
50+
- Update `docs/deployment.md` and `docs/production-config.md` when server topology or ownership changes.
51+
- If the task also includes public/admin Workers, pair this skill with `rebase-cloudflare-release`.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Rebase API Rollout"
3+
short_description: "Deploy and operate the Rebase API stack"
4+
default_prompt: "Use $rebase-api-rollout to deploy, verify, or debug the Rebase API server stack."
Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# API Rollout Runbook
2+
3+
## Primary Commands
4+
5+
```bash
6+
./ops/manage.sh check
7+
./ops/manage.sh sync
8+
./ops/manage.sh deploy api
9+
./ops/manage.sh deploy stack
10+
./ops/manage.sh ps
11+
./ops/manage.sh logs api 200
12+
./ops/manage.sh health
13+
./ops/manage.sh ready
14+
./ops/manage.sh db query "select count(*) from geekdaily_episodes;"
15+
./ops/manage.sh db backup
16+
./ops/manage.sh bootstrap-admin
17+
```
18+
19+
## Choose The Right Deploy Target
20+
21+
- `deploy api`: API code or API container changes only
22+
- `deploy stack`: API + Postgres + `cloudflared`, or infra/env changes that affect multiple services
23+
24+
## First Release Or Recovery Tasks
25+
26+
Use only when the task explicitly requires them:
27+
28+
- bootstrap first admin account
29+
- seed baseline content
30+
- DB backup before risky migrations or cleanup
31+
32+
## What `check` Should Confirm
33+
34+
`./ops/manage.sh check` should validate:
35+
36+
- SSH access works
37+
- Docker and Compose exist remotely
38+
- remote repo dir exists
39+
- compose file exists
40+
- remote env file exists
41+
- compose `ps` can run
42+
43+
## Health Endpoints
44+
45+
- `health`: quick API liveness
46+
- `ready`: API + dependency readiness
47+
48+
Both should succeed before treating the rollout as healthy.
49+
50+
## Important Repo Files
51+
52+
- `ops/manage.sh`
53+
- `infra/production/docker-compose.yml`
54+
- `infra/production/server.env.example`
55+
- `docs/deployment.md`
56+
- `docs/production-config.md`
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# API Troubleshooting
2+
3+
## `ops/manage.sh check` Fails
4+
5+
Inspect these in order:
6+
7+
1. SSH access to `rebase@101.33.75.240`
8+
2. remote repo dir exists: `/home/rebase/rebase.network`
9+
3. remote `infra/production/server.env` exists
10+
4. Docker Engine and Docker Compose plugin are installed remotely
11+
5. compose file path still matches `infra/production/docker-compose.yml`
12+
13+
## API Health Or Ready Fails
14+
15+
Run:
16+
17+
```bash
18+
./ops/manage.sh ps
19+
./ops/manage.sh logs api 200
20+
./ops/manage.sh logs cloudflared 200
21+
```
22+
23+
Then check:
24+
25+
- API container started
26+
- env values such as `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are present
27+
- DB is reachable from API
28+
- migrations or schema expectations are not blocking startup
29+
30+
## Tunnel Or Public API Hostname Fails
31+
32+
Remember the production routing model:
33+
34+
- browser -> Cloudflare -> `api.rebase.network` -> `cloudflared` -> `api:8788`
35+
36+
If `https://api.rebase.network` fails but local health is good, inspect:
37+
38+
- `cloudflared` container logs
39+
- tunnel token in `infra/production/server.env`
40+
- Cloudflare Zero Trust hostname mapping
41+
42+
## Database Checks
43+
44+
Use:
45+
46+
```bash
47+
./ops/manage.sh db query "select now();"
48+
./ops/manage.sh db query "select count(*) from geekdaily_episodes;"
49+
./ops/manage.sh db backup
50+
```
51+
52+
Do not expose Postgres publicly just to debug.
53+
54+
## Release Policy Reminder
55+
56+
The normal release policy is still:
57+
58+
- work on `dev`
59+
- validate locally
60+
- push `origin/dev`
61+
- create PR to `main`
62+
- merge through GitHub
63+
- deploy release-ready backend code from reviewed state
64+
65+
Do not bypass this just because the server is self-managed.
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
name: rebase-cloudflare-release
3+
description: Deploy and troubleshoot the Rebase Cloudflare Workers frontend stack. Use when working on `apps/web` or `apps/admin`, configuring Cloudflare Workers Builds, fixing build or deploy failures, checking custom domains, KV bindings, or compatibility date issues, or performing the Rebase `dev to main to Cloudflare` release flow.
4+
---
5+
6+
# Rebase Cloudflare Release
7+
8+
## Overview
9+
10+
Use this skill for the Rebase public and admin Workers release path. Keep the release flow anchored to the repo's `dev -> PR -> main -> Cloudflare Builds` policy and use the runbooks in `references/` before changing dashboard settings or patching build configuration.
11+
12+
## Release Workflow
13+
14+
1. Work on `dev`, not `main`.
15+
2. Validate locally before pushing:
16+
- `pnpm install --frozen-lockfile`
17+
- `pnpm --filter @rebase/web check`
18+
- `pnpm build:web:prod`
19+
- `pnpm build:admin:prod`
20+
3. Push to `origin/dev`.
21+
4. Create a pull request from `dev` to `main`.
22+
5. Merge only through GitHub; do not merge `main` locally as the normal release path.
23+
6. Let Cloudflare Workers Builds publish from `main`.
24+
7. Verify production domains after the build finishes.
25+
26+
## Current Production Split
27+
28+
- Public Worker: `rebase-web`
29+
- Public domains: `rebase.network`, `rebase.community`
30+
- Admin Worker: `rebase-admin`
31+
- Admin domain: `admin.rebase.network`
32+
- Public API origin used by Workers: `https://api.rebase.network`
33+
34+
Use `references/build-settings.md` when you need the exact dashboard settings, commands, bindings, and watch-path rules.
35+
36+
## When To Read References
37+
38+
- Read `references/build-settings.md` before editing Cloudflare dashboard settings, worker build commands, bindings, or domains.
39+
- Read `references/troubleshooting.md` when Cloudflare logs show install failures, compatibility date errors, duplicate KV provisioning, `hello world` on the production domain, or mismatched branch output.
40+
41+
## Guardrails
42+
43+
- Treat Cloudflare dashboard configuration as part of production state; update `docs/deployment.md` and `docs/production-config.md` when it changes.
44+
- Prefer `pnpm deploy:web:dry-run` and `pnpm deploy:admin:dry-run` for local verification.
45+
- Do not use local manual production deploys as the default path.
46+
- If the task also includes backend rollout, pair this skill with `rebase-api-rollout`.
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Rebase Cloudflare Release"
3+
short_description: "Deploy and debug Rebase Cloudflare Workers"
4+
default_prompt: "Use $rebase-cloudflare-release to release or debug the Rebase Cloudflare Workers stack."

0 commit comments

Comments
 (0)