mirror of
https://github.com/saltbo/zpan.git
synced 2026-09-01 15:49:00 +08:00
feat: v2.5.0 T4 — Netlify deployment target (#329)
* feat: v2.5.0 T4 — Netlify deployment target - server/entry-netlify.ts: Netlify Functions v2 (ESM) handler using hono/netlify adapter; connects to Turso via @libsql/client; skips in-process migrations (workflow applies them before deploy via drizzle-kit) - deploy/netlify/netlify.toml: build command, functions directory, SPA fallback redirect - .github/workflows/deploy-netlify.yml: 8-step workflow — secret guard, tag resolve, Turso migrations, build, netlify deploy --prod, BETTER_AUTH_SECRET first-deploy, summary - package.json: add build:netlify script (tsup ESM → netlify/functions) - docs/deploy/netlify.md: 5-section setup guide covering Turso, site creation, secrets, deploy trigger, first-boot storage setup, and cost breakdown Agent-Profile: https://agent-kanban.dev/agents/a6bb038c4226a87f * fix: address Netlify deploy review blockers BLOCKER 1 — move BETTER_AUTH_SECRET step before Deploy in workflow so the function always has the secret set before its first cold start. BLOCKER 2 — replace inline platform construction in entry-netlify.ts with createLibsqlPlatform(); removes duplicated db/schema wiring and re-unifies with the shared factory. migrate() runs at cold start and is idempotent (~50–100ms) per the workflow's prior drizzle-kit migrate. BLOCKER 3 — add --external @libsql/client to build:netlify so tsup leaves the native-binding package for Netlify to resolve; switch netlify.toml to node_bundler=esbuild so Netlify bundles @libsql/client from node_modules. Add included_files=["migrations/**"] so the migrations folder is available in the function zip for migrate(). Minor — replace 2>/dev/null with 2>&1 in deploy step so netlify-cli errors surface in CI logs instead of being silently swallowed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Bob <aibob@mails.agent-kanban.dev> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Jasper Van
@@ -0,0 +1,121 @@
|
||||
name: Deploy to Netlify
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: 'Release tag to deploy (e.g. v2.5.0). Leave empty for latest.'
|
||||
required: false
|
||||
|
||||
# Prevent overlapping deployments.
|
||||
concurrency:
|
||||
group: deploy-netlify
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
name: Deploy
|
||||
runs-on: ubuntu-latest
|
||||
# Only run on forks — the upstream repo does not deploy itself to Netlify.
|
||||
if: github.repository != 'saltbo/zpan'
|
||||
env:
|
||||
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
|
||||
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
|
||||
|
||||
steps:
|
||||
- name: Check required secrets
|
||||
env:
|
||||
HAS_TURSO_URL: ${{ secrets.TURSO_DATABASE_URL != '' }}
|
||||
HAS_TURSO_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN != '' }}
|
||||
HAS_NETLIFY_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN != '' }}
|
||||
HAS_NETLIFY_SITE: ${{ secrets.NETLIFY_SITE_ID != '' }}
|
||||
run: |
|
||||
MISSING=""
|
||||
[ "$HAS_TURSO_URL" != "true" ] && MISSING="$MISSING TURSO_DATABASE_URL"
|
||||
[ "$HAS_TURSO_TOKEN" != "true" ] && MISSING="$MISSING TURSO_AUTH_TOKEN"
|
||||
[ "$HAS_NETLIFY_TOKEN" != "true" ] && MISSING="$MISSING NETLIFY_AUTH_TOKEN"
|
||||
[ "$HAS_NETLIFY_SITE" != "true" ] && MISSING="$MISSING NETLIFY_SITE_ID"
|
||||
if [ -n "$MISSING" ]; then
|
||||
echo "::error::Missing required secrets:$MISSING"
|
||||
echo "Go to Settings → Secrets and variables → Actions to add them."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
- name: Resolve release tag
|
||||
id: release
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
INPUT_VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
if [ -n "$INPUT_VERSION" ]; then
|
||||
TAG="$INPUT_VERSION"
|
||||
else
|
||||
TAG=$(gh api repos/saltbo/zpan/releases/latest --jq '.tag_name')
|
||||
fi
|
||||
if [ -z "$TAG" ]; then
|
||||
echo "::error::No release found in saltbo/zpan"
|
||||
exit 1
|
||||
fi
|
||||
echo "version=$TAG" >> "$GITHUB_OUTPUT"
|
||||
echo "### 🚀 Deploying $TAG to Netlify" >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
repository: saltbo/zpan
|
||||
ref: ${{ steps.release.outputs.version }}
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 24
|
||||
|
||||
- run: npm ci
|
||||
|
||||
- name: Apply Turso migrations
|
||||
env:
|
||||
TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
|
||||
TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
|
||||
run: npx drizzle-kit migrate
|
||||
|
||||
- name: Ensure BETTER_AUTH_SECRET is set (first deploy only)
|
||||
env:
|
||||
USER_SECRET: ${{ secrets.BETTER_AUTH_SECRET }}
|
||||
run: |
|
||||
EXISTING=$(npx netlify env:get BETTER_AUTH_SECRET 2>&1 || true)
|
||||
if [ -n "$USER_SECRET" ]; then
|
||||
npx netlify env:set BETTER_AUTH_SECRET "$USER_SECRET" --context production
|
||||
echo "Set BETTER_AUTH_SECRET from GitHub secret"
|
||||
elif [ -z "$EXISTING" ]; then
|
||||
npx netlify env:set BETTER_AUTH_SECRET "$(openssl rand -base64 32)" --context production
|
||||
echo "Auto-generated BETTER_AUTH_SECRET"
|
||||
else
|
||||
echo "BETTER_AUTH_SECRET already set, skipping"
|
||||
fi
|
||||
|
||||
- name: Build
|
||||
run: |
|
||||
npm run build
|
||||
npm run build:netlify
|
||||
|
||||
- name: Deploy
|
||||
id: deploy
|
||||
env:
|
||||
TURSO_DATABASE_URL: ${{ secrets.TURSO_DATABASE_URL }}
|
||||
TURSO_AUTH_TOKEN: ${{ secrets.TURSO_AUTH_TOKEN }}
|
||||
run: |
|
||||
OUTPUT=$(npx netlify deploy \
|
||||
--prod \
|
||||
--dir=dist \
|
||||
--functions=netlify/functions \
|
||||
--json 2>&1)
|
||||
SITE_URL=$(echo "$OUTPUT" | jq -r '.url // .deploy_url')
|
||||
echo "url=$SITE_URL" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Write deploy summary
|
||||
run: |
|
||||
echo "**Site URL:** ${{ steps.deploy.outputs.url }}" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "Next steps:" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "1. Open the site URL and sign up as the first admin" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "2. Go to Admin → Storages → Add storage and configure your S3 bucket" >> "$GITHUB_STEP_SUMMARY"
|
||||
@@ -0,0 +1,19 @@
|
||||
[build]
|
||||
# Build the React SPA then compile the Netlify Function.
|
||||
command = "npm run build && npm run build:netlify"
|
||||
publish = "dist"
|
||||
|
||||
[functions]
|
||||
directory = "netlify/functions"
|
||||
# esbuild bundler resolves @libsql/client (external in tsup) from node_modules.
|
||||
node_bundler = "esbuild"
|
||||
# Include migration SQL files so createLibsqlPlatform can run migrate() at cold start.
|
||||
included_files = ["migrations/**"]
|
||||
|
||||
# SPA fallback — must come last; Netlify applies the first matching rule.
|
||||
# /api/* and /r/* are handled by the Netlify Function (entry-netlify.ts config.path).
|
||||
# /.netlify/functions/* is excluded from [[redirects]] automatically by Netlify.
|
||||
[[redirects]]
|
||||
from = "/*"
|
||||
to = "/index.html"
|
||||
status = 200
|
||||
@@ -0,0 +1,127 @@
|
||||
# Netlify Deployment
|
||||
|
||||
ZPan runs on Netlify via [Netlify Functions v2](https://docs.netlify.com/functions/overview/) (Node, ESM). The React SPA is served from Netlify's CDN. All API requests are handled by a single Netlify Function that connects to a [Turso](https://turso.tech) (libSQL) database.
|
||||
|
||||
**Cost:** Free tier covers 125,000 function invocations per month, 100 GB bandwidth, and unlimited static hosting. Turso's free tier covers 9 GB storage, 1 B row reads, and 25 M row writes per month — enough for personal use at $0/month.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Fork the repo** — go to [github.com/saltbo/zpan](https://github.com/saltbo/zpan) and click **Fork**.
|
||||
2. **Create a Turso database** — takes about 3 minutes:
|
||||
|
||||
```sh
|
||||
curl -sSfL https://get.tur.so/install.sh | bash
|
||||
turso auth signup # GitHub OAuth, no credit card
|
||||
turso db create zpan
|
||||
turso db show zpan --url # → TURSO_DATABASE_URL value
|
||||
turso db tokens create zpan # → TURSO_AUTH_TOKEN value
|
||||
```
|
||||
|
||||
Alternatively, use the [Turso dashboard](https://app.turso.tech) — no CLI needed.
|
||||
|
||||
3. **Create a Netlify site** — one-time setup, done in your browser:
|
||||
- Go to [app.netlify.com](https://app.netlify.com) → **Add new site → Deploy manually**.
|
||||
- Note your **Site ID** from **Site configuration → General**.
|
||||
|
||||
Or via CLI:
|
||||
|
||||
```sh
|
||||
npm install -g netlify-cli
|
||||
netlify login
|
||||
netlify sites:create --name my-zpan
|
||||
```
|
||||
|
||||
4. **Get a Netlify personal access token** — go to [app.netlify.com/user/applications](https://app.netlify.com/user/applications) → **Personal access tokens → New access token**.
|
||||
|
||||
---
|
||||
|
||||
## Add GitHub Secrets
|
||||
|
||||
In your fork, go to **Settings → Secrets and variables → Actions → New repository secret** and add:
|
||||
|
||||
| Secret | Value |
|
||||
|--------|-------|
|
||||
| `TURSO_DATABASE_URL` | `libsql://your-db-name-orgname.turso.io` |
|
||||
| `TURSO_AUTH_TOKEN` | Turso auth token from step 2 |
|
||||
| `NETLIFY_AUTH_TOKEN` | Netlify personal access token from step 4 |
|
||||
| `NETLIFY_SITE_ID` | Site ID from your Netlify site settings |
|
||||
| `BETTER_AUTH_SECRET` | *(optional)* — auto-generated on first deploy if omitted |
|
||||
|
||||
> **S3 bucket credentials are not GitHub Secrets.** After deploy, you configure storage backends via the ZPan admin UI (Admin → Storages). This keeps bucket credentials out of CI logs and lets one ZPan instance manage multiple buckets.
|
||||
|
||||
---
|
||||
|
||||
## Trigger Deploy
|
||||
|
||||
Push to `master` or go to **Actions → Deploy to Netlify → Run workflow**.
|
||||
|
||||
The workflow will:
|
||||
1. Resolve the latest ZPan release from the upstream repo
|
||||
2. Apply Turso migrations (`drizzle-kit migrate`)
|
||||
3. Build the React SPA and the Netlify Function
|
||||
4. Deploy to your Netlify site
|
||||
5. Auto-generate `BETTER_AUTH_SECRET` (first deploy only)
|
||||
6. Write the live URL to the workflow run summary
|
||||
|
||||
Subsequent pushes redeploy without re-creating resources.
|
||||
|
||||
---
|
||||
|
||||
## First-Boot Storage Setup
|
||||
|
||||
After the workflow reports success:
|
||||
|
||||
1. Open the deployed URL (shown in the workflow summary)
|
||||
2. Sign up — the first account becomes the admin
|
||||
3. Go to **Admin → Storages → Add storage**
|
||||
4. Fill in your S3-compatible bucket details (endpoint, region, access key, secret)
|
||||
5. Save — ZPan verifies the bucket is reachable and marks it active
|
||||
|
||||
This is identical to the setup flow for Cloudflare Workers and Docker deployments.
|
||||
|
||||
---
|
||||
|
||||
## Configuration & Cost
|
||||
|
||||
### Environment variables
|
||||
|
||||
Set additional env vars via the Netlify dashboard (**Site configuration → Environment variables**) or CLI:
|
||||
|
||||
```sh
|
||||
netlify env:set BETTER_AUTH_URL https://zpan.example.com --context production
|
||||
netlify env:set TRUSTED_ORIGINS https://zpan.example.com --context production
|
||||
```
|
||||
|
||||
| Variable | Required | Notes |
|
||||
|----------|----------|-------|
|
||||
| `TURSO_DATABASE_URL` | Yes | Set as a GitHub Secret; workflow passes it at build time |
|
||||
| `TURSO_AUTH_TOKEN` | Yes | Set as a GitHub Secret |
|
||||
| `BETTER_AUTH_SECRET` | Yes | Auto-generated on first deploy |
|
||||
| `BETTER_AUTH_URL` | Recommended | Set to your production URL (default: inferred from request origin) |
|
||||
| `TRUSTED_ORIGINS` | Recommended | Comma-separated allowed origins for auth cookies |
|
||||
|
||||
### Custom domain
|
||||
|
||||
In the Netlify dashboard → **Domain management → Add a domain**. No changes to the workflow required.
|
||||
|
||||
### Running migrations manually
|
||||
|
||||
```sh
|
||||
TURSO_DATABASE_URL=libsql://your-db.turso.io \
|
||||
TURSO_AUTH_TOKEN=your-token \
|
||||
npm run db:migrate
|
||||
```
|
||||
|
||||
### Free-tier limits
|
||||
|
||||
| Resource | Free limit |
|
||||
|----------|-----------|
|
||||
| Netlify Functions | 125,000 invocations/month |
|
||||
| Netlify Bandwidth | 100 GB/month |
|
||||
| Turso Storage | 9 GB |
|
||||
| Turso Row reads | 1 B/month |
|
||||
| Turso Row writes | 25 M/month |
|
||||
|
||||
Upgrade to Netlify Pro ($19/month) or Turso Scaler ($29/month) when you need more.
|
||||
@@ -10,6 +10,7 @@
|
||||
"build:node": "vite build --mode node && tsup server/entry-node.ts --format esm --outDir dist-server --external better-sqlite3 --external @libsql/client",
|
||||
"build:lambda": "tsup server/entry-lambda.ts --format cjs --outDir dist-lambda --external @libsql/client",
|
||||
"build:vercel": "vite build --mode node && tsup server/entry-vercel.ts --format esm --outDir api --external @libsql/client",
|
||||
"build:netlify": "tsup server/entry-netlify.ts --format esm --outDir netlify/functions --external @libsql/client",
|
||||
"deploy": "npm run db:migrate:d1:prod && wrangler deploy",
|
||||
"db:generate": "drizzle-kit generate",
|
||||
"db:migrate": "drizzle-kit migrate",
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
import { handle } from 'hono/netlify'
|
||||
import { createBootstrap } from './bootstrap'
|
||||
import { createLibsqlPlatform } from './platform/libsql'
|
||||
|
||||
// Migrations are applied by the deploy workflow (drizzle-kit migrate) before
|
||||
// function deployment. createLibsqlPlatform also runs migrate() at cold start —
|
||||
// it's idempotent (~50–100ms round-trip against __drizzle_migrations) and serves
|
||||
// as a safety net if a deployment ever skips the workflow migration step.
|
||||
|
||||
const platform = await createLibsqlPlatform({
|
||||
TURSO_DATABASE_URL: process.env.TURSO_DATABASE_URL!,
|
||||
TURSO_AUTH_TOKEN: process.env.TURSO_AUTH_TOKEN,
|
||||
})
|
||||
|
||||
const app = await createBootstrap(platform)
|
||||
|
||||
export default handle(app)
|
||||
|
||||
// Route all API and redirect paths to this function.
|
||||
// The SPA fallback (/* → /index.html) in netlify.toml covers everything else.
|
||||
export const config = {
|
||||
path: ['/api/*', '/r/*'],
|
||||
}
|
||||
Reference in New Issue
Block a user