Installation

By the end of this page you'll have the gpsystem CLI installed, a fresh project scaffolded, and its local dev stack (Postgres, Valkey, a mail catcher, object storage) running in Docker, ready for your first module.

Prerequisites

• Go 1.25+ (the tool directive requires Go 1.24+; the framework and every module target the current Go release)
• Node 24+ with npm: for the TypeSpec compiler; generated projects pin this version in their mise.toml
• Docker: the full dev stack (postgres, valkey, 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

Install the CLI

The framework and its 14 companion modules (errs, envconf, httperr, dbx, logx, paginate, queue, events, auth, mail, notify, storage, minio-storage-driver, telemetry) are all public, independently versioned Go modules (most pinned to a main-branch commit rather than a tagged release; see each module's own Install section). There's no private repository, no token, no special Go configuration: a plain go install resolves the CLI from the public module proxy.

go install github.com/gp-system/framework/cmd/gpsystem@latest

Pin a specific release instead of @latest when you want reproducible scaffolding across a team:

go install github.com/gp-system/framework/cmd/gpsystem@v0.0.0

Create a project

gpsystem new project shop \
  --module-path github.com/acme/shop \
  --dir ./shop
cd shop

• --module-path becomes your go.mod module and every generated import path. Pick it carefully, it is expensive to change later.
• --dir is optional (defaults to ./<name>).
• --db pgx|bun selects the database layer (default: pgx), recorded in the gpsystem.yaml manifest; every later generation follows it. Details on the new project page.

Resolve dependencies

go mod tidy

Every github.com/gp-system/* module the generated go.mod requires is public: go mod tidy resolves them straight from the module proxy, no replace directive needed. This also resolves the tool directive, so from now on the CLI runs as go tool gpsystem: pinned to a version recorded in your go.mod, identical for everyone on the team.

Install the TypeSpec toolchain

mise run setup   # npm ci / npm install

Start the local dev stack

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, valkey, mailpit, rustfs, ...)

What you get

A complete project skeleton: gpsystem.yaml manifest, TypeSpec sources under spec/typespec/, codegen configuration and chi's oapi-codegen templates under api/oapi-codegen/, 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.