Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 85 additions & 18 deletions apps/api/src/lib/asset-storage.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import { execFile } from 'node:child_process';
import { createHash, randomUUID } from 'node:crypto';
import { existsSync } from 'node:fs';
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { extname, join } from 'node:path';
import { dirname, extname, join } from 'node:path';
import { promisify } from 'node:util';

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

const findWorkspaceBinary = (binaryName: string) => {
let currentDir = process.cwd();

while (true) {
const candidate = join(currentDir, 'node_modules', '.bin', binaryName);
if (existsSync(candidate)) {
return candidate;
}

const parentDir = dirname(currentDir);
if (parentDir === currentDir) {
break;
}

currentDir = parentDir;
}

return binaryName;
};

const getWranglerExecutable = () => {
const configured = process.env.WRANGLER_BIN?.trim();
if (configured) {
return configured;
}

return findWorkspaceBinary('wrangler');
};

const toTrimmedOutput = (value: unknown) => {
if (typeof value !== 'string') {
return undefined;
}

const normalized = value.trim();
if (!normalized) {
return undefined;
}

return normalized.slice(0, 400);
};

const runWrangler = async (args: string[]) => {
const env = getEnv();
const executable = getWranglerExecutable();

try {
return await execFileAsync(executable, args, {
env: {
...process.env,
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
},
});
} catch (error) {
if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
throw serviceUnavailable('Wrangler CLI is not available for R2 uploads', {
hint: 'set WRANGLER_BIN or expose node_modules/.bin on PATH',
executable,
});
}

const details: Record<string, unknown> = {
hint: 'check the mounted Wrangler profile, CLI login state, and bucket permissions',
executable,
reason: error instanceof Error ? error.message : String(error),
};
const stderr = typeof error === 'object' && error !== null && 'stderr' in error ? toTrimmedOutput(error.stderr) : undefined;
const stdout = typeof error === 'object' && error !== null && 'stdout' in error ? toTrimmedOutput(error.stdout) : undefined;
if (stderr) {
details.stderr = stderr;
}
if (stdout) {
details.stdout = stdout;
}

throw serviceUnavailable('Wrangler CLI failed while accessing R2', {
...details,
});
}
};

const getWranglerPublicBaseUrl = async (bucket: string) => {
const cached = wranglerDevUrlCache.get(bucket);
if (cached) {
return cached;
}

const env = getEnv();
const result = await execFileAsync('wrangler', ['r2', 'bucket', 'dev-url', 'get', bucket], {
env: {
...process.env,
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
},
});
const result = await runWrangler(['r2', 'bucket', 'dev-url', 'get', bucket]);

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

try {
await writeFile(tempFile, body);
await execFileAsync(
'wrangler',
['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType],
{
env: {
...process.env,
CLOUDFLARE_ACCOUNT_ID: env.r2AccountId,
},
},
);
await runWrangler(['r2', 'object', 'put', `${env.r2Bucket}/${objectKey}`, '--remote', '--file', tempFile, '--content-type', mimeType]);
} finally {
await rm(tempDir, { recursive: true, force: true });
}
Expand Down
51 changes: 51 additions & 0 deletions skills/rebase-api-rollout/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
name: rebase-api-rollout
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.
---

# Rebase API Rollout

## Overview

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`.

## Standard Rollout

1. Keep the code on `dev` until it is validated.
2. Validate release readiness locally when needed:
- `pnpm deploy:server:config`
- any targeted API checks for the touched area
3. Use `./ops/manage.sh check` before a remote rollout.
4. Use `./ops/manage.sh deploy api` for API-only changes.
5. Use `./ops/manage.sh deploy stack` when API, Postgres, or `cloudflared` changes require the full stack.
6. Verify with:
- `./ops/manage.sh ps`
- `./ops/manage.sh health`
- `./ops/manage.sh ready`
- `./ops/manage.sh logs api 200`
7. Run targeted DB or bootstrap commands only when the task requires them.

## Current Production Topology

- host: `rebase@101.33.75.240`
- repo dir: `/home/rebase/rebase.network`
- compose file: `infra/production/docker-compose.yml`
- env file: `infra/production/server.env`
- API service: `api`
- DB service: `postgres`
- tunnel service: `cloudflared`
- public API hostname: `https://api.rebase.network`

Use `references/runbook.md` for the exact command set and `references/troubleshooting.md` for the known failure modes.

## When To Read References

- Read `references/runbook.md` before performing a routine rollout, restart, log inspection, DB query, backup, or bootstrap action.
- 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.

## Guardrails

- Prefer `ops/manage.sh` over ad-hoc SSH commands.
- Keep PostgreSQL private to the server and compose network; do not expose it publicly.
- Update `docs/deployment.md` and `docs/production-config.md` when server topology or ownership changes.
- If the task also includes public/admin Workers, pair this skill with `rebase-cloudflare-release`.
4 changes: 4 additions & 0 deletions skills/rebase-api-rollout/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Rebase API Rollout"
short_description: "Deploy and operate the Rebase API stack"
default_prompt: "Use $rebase-api-rollout to deploy, verify, or debug the Rebase API server stack."
56 changes: 56 additions & 0 deletions skills/rebase-api-rollout/references/runbook.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# API Rollout Runbook

## Primary Commands

```bash
./ops/manage.sh check
./ops/manage.sh sync
./ops/manage.sh deploy api
./ops/manage.sh deploy stack
./ops/manage.sh ps
./ops/manage.sh logs api 200
./ops/manage.sh health
./ops/manage.sh ready
./ops/manage.sh db query "select count(*) from geekdaily_episodes;"
./ops/manage.sh db backup
./ops/manage.sh bootstrap-admin
```

## Choose The Right Deploy Target

- `deploy api`: API code or API container changes only
- `deploy stack`: API + Postgres + `cloudflared`, or infra/env changes that affect multiple services

## First Release Or Recovery Tasks

Use only when the task explicitly requires them:

- bootstrap first admin account
- seed baseline content
- DB backup before risky migrations or cleanup

## What `check` Should Confirm

`./ops/manage.sh check` should validate:

- SSH access works
- Docker and Compose exist remotely
- remote repo dir exists
- compose file exists
- remote env file exists
- compose `ps` can run

## Health Endpoints

- `health`: quick API liveness
- `ready`: API + dependency readiness

Both should succeed before treating the rollout as healthy.

## Important Repo Files

- `ops/manage.sh`
- `infra/production/docker-compose.yml`
- `infra/production/server.env.example`
- `docs/deployment.md`
- `docs/production-config.md`
65 changes: 65 additions & 0 deletions skills/rebase-api-rollout/references/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# API Troubleshooting

## `ops/manage.sh check` Fails

Inspect these in order:

1. SSH access to `rebase@101.33.75.240`
2. remote repo dir exists: `/home/rebase/rebase.network`
3. remote `infra/production/server.env` exists
4. Docker Engine and Docker Compose plugin are installed remotely
5. compose file path still matches `infra/production/docker-compose.yml`

## API Health Or Ready Fails

Run:

```bash
./ops/manage.sh ps
./ops/manage.sh logs api 200
./ops/manage.sh logs cloudflared 200
```

Then check:

- API container started
- env values such as `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` are present
- DB is reachable from API
- migrations or schema expectations are not blocking startup

## Tunnel Or Public API Hostname Fails

Remember the production routing model:

- browser -> Cloudflare -> `api.rebase.network` -> `cloudflared` -> `api:8788`

If `https://api.rebase.network` fails but local health is good, inspect:

- `cloudflared` container logs
- tunnel token in `infra/production/server.env`
- Cloudflare Zero Trust hostname mapping

## Database Checks

Use:

```bash
./ops/manage.sh db query "select now();"
./ops/manage.sh db query "select count(*) from geekdaily_episodes;"
./ops/manage.sh db backup
```

Do not expose Postgres publicly just to debug.

## Release Policy Reminder

The normal release policy is still:

- work on `dev`
- validate locally
- push `origin/dev`
- create PR to `main`
- merge through GitHub
- deploy release-ready backend code from reviewed state

Do not bypass this just because the server is self-managed.
46 changes: 46 additions & 0 deletions skills/rebase-cloudflare-release/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
---
name: rebase-cloudflare-release
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.
---

# Rebase Cloudflare Release

## Overview

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.

## Release Workflow

1. Work on `dev`, not `main`.
2. Validate locally before pushing:
- `pnpm install --frozen-lockfile`
- `pnpm --filter @rebase/web check`
- `pnpm build:web:prod`
- `pnpm build:admin:prod`
3. Push to `origin/dev`.
4. Create a pull request from `dev` to `main`.
5. Merge only through GitHub; do not merge `main` locally as the normal release path.
6. Let Cloudflare Workers Builds publish from `main`.
7. Verify production domains after the build finishes.

## Current Production Split

- Public Worker: `rebase-web`
- Public domains: `rebase.network`, `rebase.community`
- Admin Worker: `rebase-admin`
- Admin domain: `admin.rebase.network`
- Public API origin used by Workers: `https://api.rebase.network`

Use `references/build-settings.md` when you need the exact dashboard settings, commands, bindings, and watch-path rules.

## When To Read References

- Read `references/build-settings.md` before editing Cloudflare dashboard settings, worker build commands, bindings, or domains.
- 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.

## Guardrails

- Treat Cloudflare dashboard configuration as part of production state; update `docs/deployment.md` and `docs/production-config.md` when it changes.
- Prefer `pnpm deploy:web:dry-run` and `pnpm deploy:admin:dry-run` for local verification.
- Do not use local manual production deploys as the default path.
- If the task also includes backend rollout, pair this skill with `rebase-api-rollout`.
4 changes: 4 additions & 0 deletions skills/rebase-cloudflare-release/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
interface:
display_name: "Rebase Cloudflare Release"
short_description: "Deploy and debug Rebase Cloudflare Workers"
default_prompt: "Use $rebase-cloudflare-release to release or debug the Rebase Cloudflare Workers stack."
Loading
Loading