Skip to content

Architecture

┌──────────────────────────── entrepot (Go binary, N replicas) ───────────────────────────┐
browser ───────► │ / React UI (embedded) │
│ /auth/* OIDC login (code + PKCE), token login, logout │
terraform, │ /api/v1/* management API ◄── api/openapi.yaml (spec-first, oapi-codegen) │
scripts ───────► │ /api/docs Swagger UI │
│ │
pip, npm, apt, │ /repository/{repo}/… ─► format.Registry ─► raw │ pypi │ npm │ apt │ yum │ helm │
dnf, helm ─────► │ /v2/…, /v2/token ─► docker (OCI distribution + token auth) │
docker, crane │ │
│ auth.Authenticator ─► authz.Authorizer (roles × bindings × repo globs) │
│ repo.Service (assets, components, serving) ─► proxy.Cache (TTL, singleflight, neg. cache)│
│ scan pipeline (queue, workers, policy) · cleanup · usage metrics · signing │
│ storage.Registry ─► BlobStore drivers: file (PVC/EBS/EFS) │ s3 │
└───────────────┬───────────────────────────────────────────────┬─────────────────────────┘
│ metadata │ content (sha256-addressed)
Postgres volumes / S3 buckets
  1. Authentication. auth.Authenticator turns the request’s credentials into a principal: a session cookie, an ent_ API token, an OIDC JWT, a GitLab id_token, a registry token or the bootstrap token. Verified bearer JWTs are cached briefly.
  2. Routing. /repository/{repo}/… loads the repository (cached for 5s) and dispatches to its format handler. Docker mounts its own /v2/ routes.
  3. Authorization. Each handler maps the operation to an action (read, write or delete) and asks authz.Authorizer, which evaluates the role bindings (also cached for 5s and invalidated on change) against the principal’s username, groups and matched GitLab policies.
  4. Hosted writes. repo.Service.Put streams the body into the repository’s blob store, hashing as it goes, then records the asset (and optionally its component) in one transaction that also maintains blob reference counts.
  5. Proxy reads. proxy.Cache.Get serves fresh cached assets. Stale ones are revalidated with conditional requests. Misses are fetched once (singleflight, detached from the client’s cancellation), stored, then served. Upstream 404s are cached negatively. If the upstream fails, stale content is served.
  6. Group reads try the members in order and merge indexes (PyPI simple pages, npm packuments, Helm index.yaml).
  7. Serving uses http.ServeContent (Range, If-None-Match, HEAD). S3 stores can redirect large downloads to presigned URLs. Quarantined components are refused here.
Task Where Coordination
Database migrations startup Postgres advisory lock
Blob garbage collection every 15 minutes, 1h grace idempotent
Scan jobs in-process workers or entrepot scan-worker FOR UPDATE SKIP LOCKED, leases, heartbeats
Scheduled rescans scanners with rescanIntervalHours job queue
Cleanup policies every cleanup.interval cluster-wide lock
Usage counters flushed every usage.flushInterval additive upserts
Table Purpose
blob_stores store name, type (file/s3) and config
repositories name, format, kind, blob store, flags, typed config (proxy/hosted/group/scan/cleanup)
blobs (store, digest) → size and reference count, for dedup and GC
components logical package versions (name + version) per repository
assets files in a repository: path → digest, content type, attrs, cached/downloaded timestamps
users, api_tokens OIDC users and service accounts; hashed tokens with scopes and expiry
roles, role_bindings, gitlab_trust_policies RBAC
scanners, scan_jobs, scan results, waivers the scanning pipeline
signing_keys per-repository OpenPGP keys (sealed)
docker_uploads in-progress chunked blob uploads
usage_minute, usage_hour, activity_events usage metrics and the activity log
audit_events who did what, from where

Implement format.Handler (Name, Kinds, ServeHTTP) using the shared services in format.Env (repository service, proxy cache, authorizer, URL helpers), and register it in internal/app/app.go. Optional interfaces:

  • format.Uploader — generic API upload,
  • format.Validator — validate repository configuration,
  • format.RootMounter — routes outside /repository/ (like Docker’s /v2/),
  • format.ClientURLer — the URL to show in client setup instructions.
cmd/entrepot/ server binary
api/openapi.yaml API contract (source of truth)
internal/api/ management API handlers (+ generated apigen)
internal/auth|authz/ authentication chain, OIDC, GitLab id_tokens, RBAC
internal/formats/ raw, pypi, npm, docker, apt, yum, helm
internal/scan/ scanning pipeline (queue, drivers, policy, GitLab feedback)
internal/cleanup|routing/ cleanup policies, routing rules
internal/signing|secrets/ repository signing keys, secrets at rest
internal/usage/ usage counters and activity log
internal/proxy/ pull-through cache
internal/repo/ repository/asset service
internal/storage/ blob store drivers (file, s3)
internal/store/ Postgres persistence (+ migrations in internal/db)
pkg/client/ generated Go API client
web/ React UI (embedded into the binary)
deploy/helm/entrepot/ Helm chart
deploy/compose/ local dev stack (Keycloak, MinIO, Postgres)