Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Local Setup

Get Aero2 running locally for development.

Prerequisites

  • Node.js 18+ (check with node --version)
  • npm (comes with Node.js)
  • Wrangler CLI (installed as a project dependency, or globally via npm install -g wrangler)

1. Install Dependencies

npm install

2. Create Local D1 Database

Apply the initial schema to a local D1 database:

npx wrangler d1 execute aero2 --local --file=./migrations/0001_initial_schema.sql

This creates a local SQLite database in .wrangler/state/ with all tables, indexes, and seed data (default roles and permissions).

3. Configure Environment Variables

Create a .dev.vars file in the project root:

# Required: Master key for encrypting secrets at rest
MASTER_KEY=local-dev-master-key-change-in-production-1234567890
 
# Optional: First user with this verified email gets admin role
BOOTSTRAP_ADMIN_EMAIL=admin@example.com
 
# Optional: GitHub OAuth (from https://github.com/settings/developers)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
 
# Optional: Google OAuth (from https://console.cloud.google.com/apis/credentials)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

The .dev.vars file is gitignored and only used during local development.

4. Configure GitHub OAuth App (Optional)

To test GitHub login locally:

  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in:
    • Application name: Aero2 Local Dev
    • Homepage URL: http://localhost:8787
    • Authorization callback URL: http://localhost:8787/rp/callback/github
  4. Copy the Client ID and Client Secret to your .dev.vars file

5. Start Development Server

npm run dev

The application will be available at http://localhost:8787.

Wrangler runs a local development server that simulates the Cloudflare Workers runtime, including D1 database access and Durable Objects.

6. Test the Login Flow

  1. Navigate to http://localhost:8787/login
  2. Click Sign in with GitHub (or another configured provider)
  3. Authorize the application
  4. You will be redirected to the dashboard showing your profile

If your email matches BOOTSTRAP_ADMIN_EMAIL, you will automatically receive the admin role.

Useful Commands

# Run unit tests
npm test
 
# Run tests in watch mode
npm run test:watch
 
# Run linting
npm run lint
 
# Fix lint errors
npm run lint:fix
 
# Generate TypeScript types from wrangler bindings
npm run cf-typegen
 
# Query local database
npx wrangler d1 execute aero2 --local --command="SELECT COUNT(*) FROM users"

Troubleshooting

"No routes matched location" error

Make sure the run_worker_first setting in wrangler.json includes your API routes. The Worker must handle API routes before the SPA catch-all.

JWT verification fails with "no applicable key found"

This usually happens after a database reset or when the Durable Object state is cleared. Clear your browser cookies and log in again to create a new session with the current keys.

Cookie not being set

Ensure you are accessing via http://localhost:8787, not http://127.0.0.1:8787. Cookie domain matching depends on the exact hostname.

D1 database errors

If you see database errors after pulling new code, re-apply migrations:

npx wrangler d1 execute aero2 --local --file=./migrations/0001_initial_schema.sql

For a fresh start, delete the local database and re-create:

rm -rf .wrangler/state/
npx wrangler d1 execute aero2 --local --file=./migrations/0001_initial_schema.sql

Port already in use

If port 8787 is already in use, Wrangler will try the next available port. Check the terminal output for the actual URL.