docz-api

module

v0.10.1 Latest Latest Go to latest Published: Sep 20, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/donaldgifford/docz-api

Links

Open Source Insights

README ¶

docz-api

A Go API for docz repos

New to the repo? Start with DEVELOPMENT.md — toolchain setup, running the service locally, Docker/compose, tests, and conventions.

Quickstart

mise install                  # toolchain
just                          # task menu
just build                    # binary at build/bin/docz-api
just test                     # race detector
just run                      # build + run the binary

Release

just release v0.1.0           # tags + pushes; CI runs goreleaser

Multi-arch archives land on the Forgejo (or GitHub) release page. Version metadata (version, commit, date) is embedded via -ldflags and surfaced in the binary's startup output.

Container

docker build -t docz-api:dev \
  --build-arg VERSION=$(git describe --tags --always) \
  --build-arg COMMIT=$(git rev-parse --short HEAD) \
  --build-arg DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) .

Image is distroless + nonroot; entrypoint is docz-api.

Layout

cmd/docz-api/    main package
internal/               library code (private to this module)
Dockerfile              multi-stage distroless build
.goreleaser.yml         release config
mise.toml               pinned toolchain
justfile                task runner

Conventions

See CLAUDE.md for the full operating notes (Go-specific + homelab universals).

License

Apache-2.0

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api holds the OpenAPI contract for docz-api's HTTP surface.	Package api holds the OpenAPI contract for docz-api's HTTP surface.
cmd
docz-api command Command docz-api is the entry point for the docz-api service.	Command docz-api is the entry point for the docz-api service.
internal
auth Package auth authenticates site users behind one Provider abstraction so the three supported login backends — GitHub (OAuth) and Okta/Keycloak (OIDC discovery) — are configured, not forked.	Package auth authenticates site users behind one Provider abstraction so the three supported login backends — GitHub (OAuth) and Okta/Keycloak (OIDC discovery) — are configured, not forked.
authhttp Package authhttp serves the four site-user auth endpoints and ties together the provider registry (internal/auth), the Redis session store (internal/session), and the durable users table (internal/store):	Package authhttp serves the four site-user auth endpoints and ties together the provider registry (internal/auth), the Redis session store (internal/session), and the durable users table (internal/store):
authorize Package authorize is the authorization seam for docz-api's read endpoints.	Package authorize is the authorization seam for docz-api's read endpoints.
config Package config loads and validates the docz-api service configuration from the environment.	Package config loads and validates the docz-api service configuration from the environment.
doczcontract Package doczcontract guards docz-api against silent drift in the pinned docz parsing library (github.com/donaldgifford/docz, pinned in go.mod).	Package doczcontract guards docz-api against silent drift in the pinned docz parsing library (github.com/donaldgifford/docz, pinned in go.mod).
githubapp Package githubapp authenticates to GitHub as the docz-api App and fetches a repo's docz content over the Git Trees API (no checkout).	Package githubapp authenticates to GitHub as the docz-api App and fetches a repo's docz content over the Git Trees API (no checkout).
httpapi Package httpapi serves the docz-api read endpoints under /api/v1: onboarded repos, repo detail, doc types, and documents.	Package httpapi serves the docz-api read endpoints under /api/v1: onboarded repos, repo detail, doc types, and documents.
ingest Package ingest runs the synchronous fetch → parse → map → upsert pipeline that turns a repo's docz content at HEAD into rows in the store.	Package ingest runs the synchronous fetch → parse → map → upsert pipeline that turns a repo's docz content at HEAD into rows in the store.
queue Package queue is the Redis-backed async ingestion layer for docz-api.	Package queue is the Redis-backed async ingestion layer for docz-api.
search Package search is the Meilisearch access layer for docz-api.	Package search is the Meilisearch access layer for docz-api.
session Package session issues and resolves Redis-backed site-user sessions.	Package session issues and resolves Redis-backed site-user sessions.
store Package store is the Postgres access layer for docz-api.	Package store is the Postgres access layer for docz-api.
store/migrations Package migrations holds the embedded goose SQL migrations for the docz-api Postgres schema.	Package migrations holds the embedded goose SQL migrations for the docz-api Postgres schema.
telemetry Package telemetry wires the docz-api observability stack (OQ 8): OpenTelemetry tracing exported over OTLP/HTTP, Prometheus metrics on /metrics, and the slog request-logging middleware.	Package telemetry wires the docz-api observability stack (OQ 8): OpenTelemetry tracing exported over OTLP/HTTP, Prometheus metrics on /metrics, and the slog request-logging middleware.
webhook Package webhook receives and verifies GitHub App webhooks, then drives onboarding and incremental refresh.	Package webhook receives and verifies GitHub App webhooks, then drives onboarding and incremental refresh.