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 bucketsRequest flow
Section titled “Request flow”- Authentication.
auth.Authenticatorturns the request’s credentials into a principal: a session cookie, anent_API token, an OIDC JWT, a GitLab id_token, a registry token or the bootstrap token. Verified bearer JWTs are cached briefly. - Routing.
/repository/{repo}/…loads the repository (cached for 5s) and dispatches to its format handler. Docker mounts its own/v2/routes. - 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. - Hosted writes.
repo.Service.Putstreams 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. - Proxy reads.
proxy.Cache.Getserves 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. - Group reads try the members in order and merge indexes (PyPI simple
pages, npm packuments, Helm
index.yaml). - Serving uses
http.ServeContent(Range, If-None-Match, HEAD). S3 stores can redirect large downloads to presigned URLs. Quarantined components are refused here.
Background work
Section titled “Background work”| 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 |
Data model
Section titled “Data model”| 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 |
Extending: adding a format
Section titled “Extending: adding a format”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.
Source layout
Section titled “Source layout”cmd/entrepot/ server binaryapi/openapi.yaml API contract (source of truth)internal/api/ management API handlers (+ generated apigen)internal/auth|authz/ authentication chain, OIDC, GitLab id_tokens, RBACinternal/formats/ raw, pypi, npm, docker, apt, yum, helminternal/scan/ scanning pipeline (queue, drivers, policy, GitLab feedback)internal/cleanup|routing/ cleanup policies, routing rulesinternal/signing|secrets/ repository signing keys, secrets at restinternal/usage/ usage counters and activity loginternal/proxy/ pull-through cacheinternal/repo/ repository/asset serviceinternal/storage/ blob store drivers (file, s3)internal/store/ Postgres persistence (+ migrations in internal/db)pkg/client/ generated Go API clientweb/ React UI (embedded into the binary)deploy/helm/entrepot/ Helm chartdeploy/compose/ local dev stack (Keycloak, MinIO, Postgres)