forgekit-dev-server

Spin up a dedicated, persistent development Forgejo instance for any project, with a single command. It generalizes the docker-compose + admin-token provisioning pattern forgekit has ad hoc in its own dev/ folder into a standalone, reusable tool any consuming project can depend on.

For the full design rationale (scope, packaging model, config shape, etc.), see SPEC.md.

Scope

Interactive local development only — not CI. If you need a Forgejo instance for automated tests, see forgekit's own testcontainers-based test-support/forgejo-container.ts instead; that's a different lifecycle (ephemeral, torn down per run) from what this tool provides (persistent, human-facing).

Installation

pnpm add -D forgekit-dev-server

Then add the scripts you want to your package.json:

// package.json
{
  "scripts": {
    "dev:forgejo": "forgekit-dev-server up",
    "dev:forgejo:down": "forgekit-dev-server down",
    "dev:forgejo:logs": "forgekit-dev-server logs",
    "dev:forgejo:status": "forgekit-dev-server status",
    "dev:forgejo:reset": "forgekit-dev-server reset"
  }
}

Configuration

Add a forgekit-dev-server.config.js next to your package.json:

// forgekit-dev-server.config.js
export default {
  name: 'my-project-dev-forgejo', // required — also becomes the Docker Compose project name
  admin: {
    username: 'dev-admin',
    email: '[email protected]',
    password: 'change-me',
  },
  port: 3000,          // optional, default 3000
  image: undefined,    // optional override of the bundled Forgejo image tag
  env: {
    baseUrl: 'FORGEJO_BASE_URL', // optional override of the .env key names
    token: 'FORGEJO_TOKEN',
  },
};

name namespaces the container, volume, and network for this project, so multiple consuming projects can each run their own instance concurrently without colliding. port avoids a host-port clash when more than one is running at once.

Usage

pnpm run dev:forgejo          # boots Forgejo, provisions an admin user + API token, prints connection details
pnpm run dev:forgejo:status   # re-prints connection details without re-provisioning
pnpm run dev:forgejo:logs     # tail container logs
pnpm run dev:forgejo:down     # stop the container (data persists in a named volume)
pnpm run dev:forgejo:reset    # stop and wipe the volume + cached admin token, for a clean slate

Re-running up is safe — it reuses the existing admin token instead of provisioning a new one. On success, up upserts FORGEJO_BASE_URL / FORGEJO_TOKEN (or your configured key names) into your project's own .env, without touching any other keys already in that file.

Run forgekit-dev-server --help (or -h) for the command list without leaving your terminal.

The admin token is cached at ~/.forgekit-dev-server/<name>/admin-token — reset it along with the instance's data via reset.

Local development (on this repo)

pnpm install
pnpm run build         # tsup
pnpm run dev            # tsup --watch
pnpm run lint           # biome check
pnpm run typecheck      # tsc --noEmit

Tests

pnpm run test:unit         # fast, no external dependencies
pnpm run test:integration  # drives a real docker compose lifecycle — needs Docker
pnpm run test              # both

Before handing over any change, run pnpm run ai-verify (lint + typecheck + unit tests scoped to what changed).

Related

• forgekit — the Forgejo API client SDK this tool is named alongside. Not a dependency: the one thing this tool needs from a Forgejo instance — bootstrapping the very first admin user — requires forgejo admin user create (a CLI command with direct database access), since Forgejo's admin API itself requires an existing admin token to call. See SPEC.md §5.
• Any Forgejo instance serves its own interactive API reference at <baseUrl>/api/swagger (e.g. http://localhost:3000/api/swagger) — the canonical source for what you can do with the token this tool hands you.

License

AGPL-3.0-or-later. If AGPL's terms don't work for your use case (e.g. you want to use forgekit-dev-server in closed-source software), open an issue on this repo — alternative licensing arrangements can be discussed.