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

Quickstart

Get Aero2 running locally in 5 minutes.

Prerequisites

1. Install Dependencies

npm install

2. Create Local D1 Database

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

3. Configure Environment Variables

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

# Required: Master key for encrypting secrets
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

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.

6. Test the Login Flow

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

Project Structure

src/
├── backend/
│   ├── index.ts          # Main Hono app and route mounting
│   ├── rp.ts             # Relying Party routes (OAuth client flow)
│   ├── op.ts             # OIDC Provider routes (token issuance)
│   ├── idp.ts            # Identity Provider management API
│   ├── clients.ts        # OAuth client management API
│   ├── roles.ts          # Role management API
│   ├── jwks.ts           # JWKS Durable Object for key management
│   ├── middleware/
│   │   └── auth.ts       # Authentication and authorization middleware
│   └── utils/
│       ├── token.ts      # JWT signing and verification
│       └── crypto.ts     # Encryption and hashing utilities
├── frontend/
│   ├── pages/            # React pages (Login, Dashboard, Admin)
│   ├── contexts/         # Auth context
│   └── routes.tsx        # React Router configuration
└── migrations/
    └── 0001_initial_schema.sql

Troubleshooting

"No routes matched location" error

Make sure the run_worker_first setting in wrangler.json includes your API routes.

JWT verification fails with "no applicable key found"

This usually happens after a database reset. Clear your browser cookies and log in again.

Cookie not being set

Ensure you're accessing via http://localhost:8787, not 127.0.0.1.