Local Development Setup

This document covers running the full Aelghar stack locally with Wrangler's local simulation layer, and explains the staging environment workflow for pre-production testing.

---

Prerequisites

• Node.js 20+
• wrangler CLI: npm install -g wrangler
• Cloudflare account authenticated: wrangler login
• Python 3.10+ (for MkDocs build only — not required for app dev)

---

Running the Worker Locally

Wrangler simulates D1, KV, DO, and R2 locally using SQLite and in-process storage. No network calls to Cloudflare during development.

wrangler dev --local

This starts the Worker on http://localhost:8787.

With persistent local D1 (recommended): local D1 data survives restarts when stored in .wrangler/state/:

wrangler dev --local --persist-to .wrangler/state

Run local migrations on first start:

wrangler d1 migrations apply --database-name aelghar-db --local --persist-to .wrangler/state

---

Running SvelteKit Against the Local Worker

SvelteKit Pages dev server uses Vite. To proxy API calls to the local Worker, configure vite.config.ts:

// vite.config.ts
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [sveltekit()],
  server: {
    proxy: {
      '/api': 'http://localhost:8787',
      '/admin': 'http://localhost:8787',
    },
  },
});

Start SvelteKit:

npm run dev

The app will be at http://localhost:5173. API calls to /api/* proxy to the local Worker.

---

Seeding Local D1

After running migrations, seed the world towns and initial reserves:

# Seed town rows (runs migration 0100_seed_towns.sql)
wrangler d1 migrations apply --database-name aelghar-db --local --persist-to .wrangler/state

# Load content (creatures, items, expeditions, board orders, skills)
# Worker must be running first
curl -X POST http://localhost:8787/admin/content/reload `
  -H "Authorization: Bearer dev-admin-secret"

For local dev, set a ADMIN_SECRET in a .dev.vars file (never commit this file):

# .dev.vars  (add to .gitignore)
ADMIN_SECRET=dev-admin-secret
JWT_SECRET=dev-jwt-secret-32-bytes-minimum-for-hmac
REFRESH_SECRET=dev-refresh-secret
TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA   # Cloudflare test key (always passes)

Wrangler loads .dev.vars automatically during wrangler dev.

---

Turnstile in Local Dev

Cloudflare provides test keys that bypass the actual challenge:

• Test site key (always passes): 1x00000000000000000000AA
• Test secret key (always passes): 1x0000000000000000000000000000000AA

Set the secret key in .dev.vars and the site key in your local SvelteKit env:

# .env.local (SvelteKit)
PUBLIC_TURNSTILE_SITE_KEY=1x00000000000000000000AA

---

Local KV and DO

Wrangler local simulates KV and DO with SQLite-backed state under .wrangler/state/. There is no separate setup needed — they are automatically available during wrangler dev --local.

KV namespaces in local mode are keyed by binding name (KV). DO state is stored per-class under .wrangler/state/v3/do/.

---

Staging Workflow

Staging is a real Cloudflare environment with a dedicated D1, KV, and Worker deployment. Use it to test before every production deploy.

Branch-Based Staging Deploys

1. Push changes to a staging branch
2. CI (GitHub Actions or manual) runs:

   wrangler deploy --env staging
   wrangler d1 migrations apply --database-name aelghar-db-staging --env staging
   

3. Load content on staging Worker:

   curl -X POST https://aelghar-api-staging.<account>.workers.dev/admin/content/reload `
     -H "Authorization: Bearer $env:ADMIN_STAGING_SECRET"
   

4. Run smoke tests against staging
5. If passing → deploy to production

Manual Staging Deploy

# From repo root
.\scripts\deploy-pages.ps1 -ProjectName aelghar-docs-staging -Env staging

Staging Data

Staging D1 data is independent from production. It is safe to wipe and re-seed staging at any time:

# Reset staging D1 (destructive — staging only)
wrangler d1 execute aelghar-db-staging --env staging --command "PRAGMA wal_checkpoint; DELETE FROM town;"
wrangler d1 migrations apply --database-name aelghar-db-staging --env staging

---

Common Dev Tasks

Task	Command
Start Worker locally	wrangler dev --local --persist-to .wrangler/state
Run migrations locally	wrangler d1 migrations apply --database-name aelghar-db --local --persist-to .wrangler/state
Query local D1	wrangler d1 execute aelghar-db --local --persist-to .wrangler/state --command "SELECT * FROM town"
Seed content	curl -X POST http://localhost:8787/admin/content/reload -H "Authorization: Bearer dev-admin-secret"
Start SvelteKit	npm run dev
Build MkDocs	python -m mkdocs build 2>&1 \| Select-Object -Last 5
Deploy docs	.\scripts\deploy-pages.ps1 -ProjectName aelghar-docs 2>&1 \| Select-Object -Last 5
Deploy Worker staging	wrangler deploy --env staging
Deploy Worker prod	wrangler deploy
View local KV	wrangler kv key list --namespace-id KV --local --persist-to .wrangler/state

---

.gitignore Additions

The following paths must not be committed:

.dev.vars
.wrangler/
.env.local