Installation

Prerequisites

• Go 1.25+ (Fiber v3 requires it; the tool directive requires Go 1.24+)
• Node 24+ with npm: for the TypeSpec compiler; generated projects pin this version in their mise.toml
• Docker: the full dev stack (postgres, redis, mailpit, rustfs, app modules) runs from compose.yml; docker compose ≥ 2.17 + BuildKit required (additional_contexts + cache mounts in the Dockerfile)
• docker network create proxynet: the stack is exposed via Traefik labels on an external network shared across the workspace; one-time, shared across projects
• mise is recommended; generated projects ship a mise.toml with pinned tool versions and tasks
• Access to the kit repository: the kit is private, so the Go toolchain needs extra configuration; the next section covers it

Accessing the private kit

The kit module (github.com/gp-system/gpsystem) lives in a private repository. By default the Go toolchain downloads through the public module proxy and verifies against the checksum database. Both fail for a private module, so without configuration both go run ...@latest and go mod tidy error out. Pick one of two paths.

Local checkout (for kit development)

While the kit is pre-1.0 and under active development, this is the recommended path: it needs no git authentication and no Go configuration, because everything resolves locally.

git clone git@github.com:gp-system/gpsystem.git /path/to/gpsystem

go run /path/to/gpsystem/cmd/gpsystem new project shop \
  --module-path github.com/acme/shop \
  --kit-replace /path/to/gpsystem

--kit-replace writes a replace directive into the generated go.mod (resolving the given path to an absolute one), so go mod tidy resolves the kit from the local checkout: no network, no authentication.

Private repo via the Go toolchain

For teammates who use the kit but don't develop it: after a one-time setup, the Go toolchain works directly against the private GitHub repository.

1. GOPRIVATE

go env -w GOPRIVATE=github.com/gp-system/*

For the matching path pattern this disables the module proxy and the checksum-database verification (no separate GONOSUMDB needed). From here on Go fetches the module straight from git.

2. Git authentication

Under the hood go clones with git, so git must be able to authenticate against GitHub. Two proven variants:

# assuming your SSH key is registered in your GitHub account
git config --global url."git@github.com:".insteadOf "https://github.com/"

# fine-grained personal access token with read access to the kit repo
machine github.com
login <github-username>
password <personal-access-token>

3. Verify

go run github.com/gp-system/gpsystem/cmd/gpsystem@latest version

If it prints the kit module and version, the setup works: scaffolding and go mod tidy will work too.

CI setup (GitHub Actions)

There is no interactive authentication in CI: alongside GOPRIVATE you need a token-based insteadOf rewrite.

env:
  GOPRIVATE: github.com/gp-system/*

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-go@v5
    with:
      go-version: "1.25"
  - name: Grant access to the private kit
    run: |
      git config --global \
        url."https://x-access-token:${{ secrets.KIT_READ_TOKEN }}@github.com/".insteadOf \
        "https://github.com/"
  - run: go build ./...

KIT_READ_TOKEN is a fine-grained personal access token (or an organization fine-grained token) with read access to the kit repository only, stored as a repository secret. The built-in Actions GITHUB_TOKEN is not enough: it only grants access to the running repository, not to the kit's.

Create a project

go run /path/to/gpsystem/cmd/gpsystem new project shop \
  --module-path github.com/acme/shop \
  --kit-replace /path/to/gpsystem
cd shop

go run github.com/gp-system/gpsystem/cmd/gpsystem@latest \
  new project shop --module-path github.com/acme/shop
cd shop

go mod tidy

mise run setup   # npm ci / npm install

cp .env.example .env               # set USER_ID/GROUP_ID to id -u / id -g
docker network create proxynet     # one-time
mise run dev                       # build + start the full stack (postgres, redis, mailpit, rustfs, ...)

What you get

A complete project skeleton: gpsystem.yaml manifest, TypeSpec sources under spec/typespec/, codegen configuration and the chosen engine's oapi-codegen templates under api/oapi-codegen/ (the kit's full template set for Fiber, minimal overrides for chi), env-based configuration, compose file, lint config and mise tasks. The full tree is described in Project structure.

There are no modules yet. Create the first one next: Your first module.