OpenArtifact documentation
Self-hosted artifact repository for many package formats. The project README is the short overview; the details are here.
These pages are also published, one version per release, at https://openartifact.github.io/ with search and a version switcher; the markdown stays readable on GitHub. latest follows main.
Getting started
| Page | Contents |
|---|---|
| Installation | Docker Compose, Helm, release binaries and source builds; first login and password reset; installing the web UI as an app (PWA) |
| Web UI | The seven areas, the Ctrl/Cmd+K command palette, the settings hub, the artifact page and where the old URLs went |
| Configuration | Load order, env-only variables, and every setting with env var, YAML key and default |
| Language | Choosing the UI language: browser default, the picker in the user menu and on the sign-in page, where the choice is stored, what follows it |
| Upgrading | Forward-only migrations, image tags, per-method upgrade steps, secrets to keep, rollback |
Package formats
| Page | Contents |
|---|---|
| Format matrix | Client URLs, hosted/proxy/group support, upload methods, authentication |
| Client setup | Configure and publish commands for every client, generated from the same source as the web UI |
| Maven · npm · PyPI · Docker/OCI | Client setup and publishing |
| Helm · Debian · RPM · Arch Linux · Go | Client setup and publishing |
| Cargo · NuGet · RubyGems · Conda | Client setup and publishing |
| Conan · Alpine (apk) · Terraform/OpenTofu · Ivy and sbt · Raw | Client setup and publishing |
Repositories
| Page | Contents |
|---|---|
| Hosted, proxy and group | Repository types, proxy cache and serve-stale, groups, the public flag |
| Cleanup and quotas | Cleanup policies, per-repository and per-project storage quotas, project default cleanup policies |
| Trash | Deleted artifacts and repositories stay restorable for a retention period; immutable releases |
| Properties | Artifact key/value properties: API, limits, search |
| Release bundles | Release bundles and promotion pipelines |
| Migrating from Nexus / Artifactory | oa import: flags, retries, what is preserved |
Security
| Page | Contents |
|---|---|
| Authentication | Local login, sessions, CSRF, API tokens, legacy key, anonymous access, IP and rate limits |
| Single sign-on | OIDC and SAML providers, provisioning, group mapping |
| RBAC | Users, groups, permission targets, request-to-action mapping, projects (repository ownership, member and group access) |
| Projects | Project roles, member and group self-service, who may create projects, audit events, API |
| Scanning | Vulnerability, secret and license scans, quarantine |
| Security findings | The findings of all repositories in one list (vulnerabilities, licenses, secrets, AI), summary, export, scanner health and the per-repository counts |
| SBOM and VEX | CycloneDX / SPDX 2.3 and 3.0 SBOMs, OpenVEX / CycloneDX VEX, signed attestations (cosign), Trivy, Grype |
| Dependency-Track | Pushing the BOM on upload and scan and the VEX after analysis; project naming, permissions, per-repository overrides |
| License metadata | How licenses are read from package files: precedence per format, unresolved licenses, limits and limitations |
| Signing | GPG key management and signing of APT/RPM metadata and release bundles; verifying release archives and images |
Operations
| Page | Contents |
|---|---|
| Storage | Blob backends and their settings, content addressing, deduplication |
| Storage tiers | Named tiers on several backends, lifecycle policies, the crash-safe mover, promote-on-read, dry run |
| Trash | Soft delete: retention, restore, purge, immutable releases, repository delete confirmation |
| Blob replication | Async second copy of every blob on another backend, read fallback, verify and repair, loss of the primary store |
| Backup | Backup and restore of records and blobs |
| Federation | Peer-to-peer replication of hosted repositories between instances: setup, conflicts, resync, monitoring |
| Disaster recovery | Runbook: database lost, storage lost, one repository deleted; RPO and RTO per option, verification commands |
| PostgreSQL point-in-time recovery | WAL archiving, base backups and restore to a chosen time with CloudNativePG and the Helm chart |
| Rebuild from storage | Row journal sidecars in the blob store and openartifact rebuild: re-index an empty database from storage |
| Monitoring | Health, Prometheus metrics, audit log, logging |
| Audit log retention | Delete audit entries older than N days in paced batches, one replica at a time; export first |
| White-label branding | Product name, logos, favicon, accent colour, login message and support link: configuration, admin UI, API, SVG sanitising, the source-code attribution that stays |
| Webhooks | Events, HMAC signatures, retries, delivery log |
| Performance | Benchmarks, load tests, pprof, auth cache and other tuning |
Integrations
| Page | Contents |
|---|---|
| CLI | oa commands (including trash and repository delete confirmation), login and configuration |
| CI integration | Upload, bundle and promote from Jenkins, Drone, Woodpecker or any shell with oa; least-privilege CI tokens |
| Declarative configuration | oa apply, oa diff and oa export: manage users, repositories, permissions and more from YAML manifests, GitOps usage |
| MCP server | Tools, permissions and client configuration (Claude, Cursor, VS Code, Codex, omp) |
| REST API | OpenAPI spec, interactive API reference, authentication, conventions |
| AI analysis | Optional LLM analysis of package manifests |
| yap | Build deb/rpm packages with yap, publish them and install from clients |
Reference
Generated from the code (make docs-gen), never hand-edited.
| Page | Contents |
|---|---|
| Overview | What is generated and how |
| Configuration keys | Every YAML key with env var, type, default and description |
| Metrics | Every Prometheus metric with type, labels and help |
| CLI commands | oa command and flag reference |
| REST API | Endpoints per tag with parameters, bodies and responses, rendered from openapi.json |
Development
| Page | Contents |
|---|---|
| Development guide | Toolchain, build, test, lint, generate, CI and release pipeline |
| Translating the web UI | Catalog layout, adding UI text, the i18n:check rules, adding a language, correcting a translation by pull request |
| Architecture | Code layout, request flow, routing invariant, storage and database split |
| Design: federated repositories | Multi-site replication: unit log, pull protocol, conflict rules, tombstones, peer authentication, supported formats |
Contributor rules: CONTRIBUTING.md and AGENTS.md. Security reports: SECURITY.md.