INVOKEIL

Open-source third-level domain and DNS management for `invokeil.cfd`

Create, manage, and connect project domains through GitHub authentication, provider templates, and controlled DNS records—powered by Cloudflare. Users can create a domain such as project.invokeil.cfd and add deeper hostnames such as api.project.invokeil.cfd.

Live Website · API · Get Started · Deployment

InvokeIL provides a focused, secure workflow for creating free subdomains under invokeil.cfd and connecting them to hosted applications, APIs, and other services.

Overview

InvokeIL is an open-source subdomain and DNS management platform for invokeil.cfd. Users authenticate with GitHub, create a subdomain, and connect their projects using provider templates or custom DNS records.

The platform is split into two independently deployable applications:

Application	Technology	Responsibility	Production endpoint
`apps/api`	Hono on Cloudflare Workers	Authentication, sessions, subdomain management, DNS operations, ownership checks, and owner APIs	`api.invokeil.cfd`
`apps/web`	Next.js static export on Cloudflare Pages	Responsive dashboard, landing page, SEO assets, and user-facing DNS management flows	`invokeil.cfd`

The API uses Cloudflare D1 for relational data and Cloudflare KV for session storage. Browser sessions are represented only by an HttpOnly and Secure cookie.

Features

User-facing capabilities

GitHub OAuth authentication.
Free subdomain creation under invokeil.cfd.
Public, rate-limited subdomain availability checks.
Support for A, CNAME, TXT, and MX records.
Provider templates for common hosting platforms.
Two-step domain flow: claim a third-level domain first, then configure DNS from its realtime manager.
Inline editing for DNS record type, name, content, TTL, and MX priority.
Responsive dashboard and mobile-friendly creation flow.
Cloudflare-backed SSL protection for InvokeIL subdomains.

Administration and platform capabilities

Owner-only search, status management, restriction, restoration, deletion, and audit APIs.
Ownership validation based on the stable numeric GitHub account ID rather than a username.
Session fallback behavior that safely returns users to the homepage when the session store is unavailable.
Static SEO, Open Graph, PWA, sitemap, robots, and branded 404 assets.
Lightweight InvokeIL visual branding with Nunito typography.

Architecture

flowchart LR
    User[User browser]
    Web[Cloudflare Pages\napps/web\nNext.js static export]
    API[Cloudflare Worker\napps/api\nHono API]
    D1[(Cloudflare D1\nsubdomain and DNS data)]
    KV[(Cloudflare KV\nsessions)]
    GH[GitHub OAuth]
    DNS[Cloudflare DNS API]

    User -->|HTTPS| Web
    Web -->|Credentialed API requests| API
    API -->|OAuth flow| GH
    API --> D1
    API --> KV
    API -->|DNS operations| DNS

Production request flow

URL	Route	Service
`https://invokeil.cfd`	Frontend	Cloudflare Pages → `invokeil-web`
`https://api.invokeil.cfd`	Backend API	Cloudflare Worker → `invokeil-api`

The frontend sends credentialed requests directly to the API. Session state remains server-controlled: the session record is stored in KV, while the browser receives only the secure session cookie.

Domain setup is intentionally two-step. POST /api/subdomains claims an authenticated user's third-level domain without DNS records. The realtime manager at /manage/realtime?domainId=<domain-id> then calls the authenticated POST /api/subdomains/:domainId/records endpoint to validate and append a provider template or custom records. Existing records remain editable through the authenticated PATCH /api/subdomains/:domainId/records/:recordId endpoint.

Repository Structure

.
├── apps/
│   ├── api/
│   │   ├── migrations/          # D1 migrations for existing installations
│   │   ├── src/db/schema.sql    # Initial D1 schema for fresh installations
│   │   └── ...                  # Hono Worker source and tests
│   └── web/
│       └── ...                  # Next.js static-export frontend
└── README.md

Requirements

Before installing the project, make sure the following are available:

Requirement	Version or access
Node.js	24 or newer
pnpm	11 or newer
Cloudflare	Workers, D1, KV, and Pages access
GitHub	OAuth application for local and/or production authentication

You can verify the local toolchain with:

node --version
pnpm --version

Getting Started

1. Clone the repository

git clone <your-repository-url>
cd <repository-directory>

2. Install dependencies

Install dependencies separately for each application:

cd apps/api
pnpm install

cd ../web
pnpm install

3. Authenticate Wrangler

From apps/api, authenticate Wrangler with an account that has access to the required Cloudflare resources:

cd apps/api
pnpm exec wrangler login

Create or select the D1 database and KV namespace, then place the resulting resource IDs in apps/api/wrangler.toml.

4. Initialize D1

For a fresh installation, apply the initial schema. For an existing installation, apply migrations as appropriate for your environment:

cd apps/api

# Fresh database
pnpm exec wrangler d1 execute invokeil --remote --file src/db/schema.sql

# Existing database with migrations
pnpm exec wrangler d1 migrations apply invokeil --remote

Important: Confirm the database name and Wrangler environment before using --remote. Running a command against the wrong environment can modify production data.

Environment Configuration

No secrets belong in this repository. Use Wrangler secrets for deployed Workers and an ignored apps/api/.dev.vars file for local development.

API secrets and variables

Configure the following values in the intended Worker environment:

Name	Purpose	Secret?
`GITHUB_CLIENT_ID`	GitHub OAuth client identifier	No*
`GITHUB_CLIENT_SECRET`	GitHub OAuth client secret	Yes
`SESSION_SECRET`	Secret used to protect session handling	Yes
`CF_DNS_TOKEN`	Cloudflare token for DNS operations	Yes
`CF_ZONE_ID`	Cloudflare zone identifier for `invokeil.cfd`	No*
`OWNER_GITHUB_ID`	Stable numeric GitHub account ID for owner authorization	No*

*Although these values are not always confidential, keep all environment-specific configuration out of source control.

Set Worker secrets with Wrangler, for example:

cd apps/api
pnpm exec wrangler secret put GITHUB_CLIENT_SECRET
pnpm exec wrangler secret put SESSION_SECRET
pnpm exec wrangler secret put CF_DNS_TOKEN

For local development, create apps/api/.dev.vars:

GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
SESSION_SECRET=use-a-long-random-local-secret
CF_DNS_TOKEN=your_cloudflare_dns_token
CF_ZONE_ID=your_cloudflare_zone_id
OWNER_GITHUB_ID=your_numeric_github_account_id

Ensure .dev.vars is ignored by Git and never commit real credentials. Use the production OWNER_GITHUB_ID only in the environment where it is intended to grant owner access.

Frontend configuration

The web application is a static export. To point it at a local API, configure NEXT_PUBLIC_API_URL in the web environment:

NEXT_PUBLIC_API_URL=http://localhost:8787

The production default API URL is:

https://api.invokeil.cfd

Because NEXT_PUBLIC_* variables are embedded into the frontend build, do not place secrets in them.

Local Development

Run the API and web applications in separate terminals.

Terminal 1: API

cd apps/api
pnpm run dev

The local API is expected to run at http://localhost:8787.

Terminal 2: Web

cd apps/web
pnpm run dev

Open the frontend at http://localhost:3000.

For local GitHub OAuth, configure the callback URL in the GitHub OAuth application to match the local API callback route used by the project.

Testing and Validation

Run backend tests and type checking:

cd apps/api
pnpm test
pnpm exec tsc --noEmit

Run frontend linting and generate the static export:

cd apps/web
pnpm run lint
pnpm run build

The test suite includes focused coverage for OAuth callbacks, sessions, subdomain ownership, availability checks, owner authorization, DNS templates, two-step record persistence, and rollback behavior.

Before opening a pull request, validate both applications and confirm that the generated frontend output contains no secrets or server-only configuration.

Deployment

Deploy the API Worker

cd apps/api
pnpm run deploy

Before deploying, confirm that the correct Wrangler account, environment, D1 binding, KV binding, and secrets are selected.

Deploy the Pages frontend

cd apps/web
pnpm run build
pnpm dlx wrangler pages deploy out --project-name invokeil-web

Before production deployment, inspect apps/web/out and verify that no secret values are present. Only public frontend configuration should be included in the static export.

Recommended release checklist

Check	Status
Backend tests pass	☐
TypeScript validation passes	☐
Frontend lint passes	☐
Static frontend build succeeds	☐
D1 migrations reviewed	☐
Production secrets configured in Wrangler	☐
GitHub OAuth callback URLs verified	☐
Cloudflare DNS token scope reviewed	☐
Generated `apps/web/out` checked for secrets	☐
Smoke test completed for login, creation, editing, and logout	☐

Features

GitHub OAuth with KV-backed sessions
Free third-level domain creation under invokeil.cfd
Domain-only creation followed by /manage/realtime?domainId=<domain-id> DNS configuration
A, CNAME, TXT, MX, and scoped NS record support
DNS templates for popular hosting providers
Public, rate-limited domain availability checks
Owner-only search, status management, restriction, restore, delete, and audit APIs
Responsive dashboard and mobile creation flow
Active domain management with contained DNS record controls
Clean hostname display with clickable domain links
Inline editing for active DNS record type, name, content, TTL, and MX priority
Cloudflare-backed SSL protection for InvokeIL domains
Nunito typography and light InvokeIL brand artwork across the web interface
Static SEO, Open Graph, PWA, sitemap, robots, and branded 404 assets

Security

InvokeIL handles authentication and DNS operations, so secure configuration is essential.

Never commit .dev.vars, OAuth secrets, session secrets, Cloudflare tokens, or other credentials.
Use the least-privileged Cloudflare API token capable of performing the required DNS operations.
Treat SESSION_SECRET as a high-value secret and use a long, random value.
Keep OWNER_GITHUB_ID environment-specific and verify that it is the stable numeric GitHub account ID.
Use credentialed HTTPS requests in production and confirm cookie settings remain HttpOnly and Secure.
Review D1 migrations before applying them to a remote database.
Confirm the target Wrangler environment before executing any command with --remote.
Never expose server-only variables through NEXT_PUBLIC_* configuration.

If you discover a security issue, avoid publishing exploit details in a public issue. Contact the project maintainers privately through the repository’s supported security channel.

Troubleshooting

The frontend cannot reach the API

Check that the API is running, NEXT_PUBLIC_API_URL points to the correct origin, and the browser is sending credentialed requests to the expected API URL. For production, verify the api.invokeil.cfd DNS route and Worker deployment.

GitHub OAuth redirects to the wrong place

Verify that the callback URL configured in the GitHub OAuth application exactly matches the environment in use. Local and production callbacks must be configured separately when both environments are supported.

D1 commands fail

Confirm that Wrangler is authenticated, the database binding name is invokeil, the database ID in wrangler.toml is correct, and the command is being executed from apps/api.

Owner actions are denied

Confirm that OWNER_GITHUB_ID contains the stable numeric GitHub account ID, not a GitHub username or display name, and that the value is configured in the active Worker environment.

DNS changes fail

Verify the Cloudflare zone ID, token permissions, token environment, and target record values. Use a narrowly scoped token and inspect Worker logs without printing secret values.

Contributing

Contributions are welcome. Before submitting a pull request, describe the problem being solved, keep changes scoped, run the backend and frontend validation commands, and include relevant tests for behavior changes. Avoid committing generated files, credentials, or environment-specific configuration.

License

InvokeIL is released under the MIT License.

Built for simple, controlled, and developer-friendly subdomain management.

Name		Name	Last commit message	Last commit date
apps		apps
.gitignore		.gitignore
Invokeil.svg		Invokeil.svg
Invokeil_cropped.svg		Invokeil_cropped.svg
LICENSE		LICENSE
PHASE_5_1_AUDIT_CHECKLIST.md		PHASE_5_1_AUDIT_CHECKLIST.md
README.md		README.md
invokeil_text.svg		invokeil_text.svg

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

INVOKEIL

Open-source third-level domain and DNS management for invokeil.cfd

Contents

Overview

Features

User-facing capabilities

Administration and platform capabilities

Architecture

Production request flow

Repository Structure

Requirements

Getting Started

1. Clone the repository

2. Install dependencies

3. Authenticate Wrangler

4. Initialize D1

Environment Configuration

API secrets and variables

Frontend configuration

Local Development

Terminal 1: API

Terminal 2: Web

Testing and Validation

Deployment

Deploy the API Worker

Deploy the Pages frontend

Recommended release checklist

Features

Security

Troubleshooting

The frontend cannot reach the API

GitHub OAuth redirects to the wrong place

D1 commands fail

Owner actions are denied

DNS changes fail

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Open-source third-level domain and DNS management for `invokeil.cfd`