Nexspence

---

🎬 Demo

▶️ Watch the demo on nexspence.com

---

What is Nexspence?

Nexspence is a self-hosted artifact repository manager that supports 19 package formats, three repository types (hosted, proxy, group), fine-grained RBAC, SSO via OIDC/LDAP, audit logging, S3-compatible storage, and a modern dark-theme web UI — all in a single binary backed by PostgreSQL. It exposes the full Sonatype Nexus v1 REST API at /service/rest/v1/ for drop-in compatibility with existing CI/CD pipelines and package manager configs.

---

Architecture

One Go binary — Gin HTTP layer, embedded React UI, pluggable artifact formats. Every node is stateless; all state lives in PostgreSQL, blob storage, and (for HA) Redis, so scaling out is a matter of running more nodes behind the load balancer.

View the full site with interactive architecture diagram, install guide, and comparison: nexspence.com →

---

Screenshots

Dashboard & Repositories

Admin & Security

Cleanup & Search

OCI, Vulnerabilities & Monitoring

---

Quick Start

Requirements: Docker 24+ with Compose v2

git clone https://github.com/nexspence/nexspence
cd nexspence
docker compose up -d

Service	URL	Default credentials
Web UI & REST API	http://localhost:8081	admin / admin123
Docker registry	localhost:5001	same credentials
PostgreSQL	localhost:5437	nexspence / nexspence

Change the admin password immediately after first login.

Docker Compose Profiles

The compose file uses profiles to opt into optional services. Combine as needed:

Profile	Adds	Command
(none)	Nexspence + PostgreSQL + MinIO	docker compose up -d
monitoring	Prometheus + Grafana	docker compose --profile monitoring up -d
keycloak	Keycloak OIDC IdP	OIDC_ENABLED=true docker compose --profile keycloak up -d
keycloak + monitoring	Both	OIDC_ENABLED=true docker compose --profile keycloak --profile monitoring up -d
dev	Vite frontend dev server	docker compose --profile dev up

Monitoring setup — before starting the monitoring profile, create a Bearer token:

# Copy the example and fill in a valid nxs_* API token
cp deploy/monitoring/prometheus-token.example deploy/monitoring/prometheus-token
# edit the file and paste your token

Once running: Prometheus at http://localhost:9090 · Grafana at http://localhost:3000 (admin / admin)

The pre-built Grafana dashboard (Nexspence Overview) loads automatically with 8 panels: requests/sec, error rate, latency p95, artifacts, storage, downloads, goroutines, memory.

Standalone monitoring (target an existing Nexspence instance):

cd deploy/monitoring
NEXSPENCE_URL=http://my-server:8081 docker compose up -d

For all deployment variants (MinIO, HA cluster, Keycloak SSO, from source) see the documentation.

---

Native Install (no Docker)

Prefer running on bare metal? Download the .deb/.rpm (Linux) or the macOS/Windows archive from the latest release. Each ships with systemd / launchd / Windows-service integration, and the binary embeds the web UI (self-contained). Full walkthrough — including reverse-proxy (nginx/Caddy) and multi-node load-balancer setups — in the documentation. Requires an external PostgreSQL.

---

CLI Tool — nxs

Manage Nexspence from the terminal or CI/CD pipelines:

# Install
curl -sSfL https://raw.githubusercontent.com/nexspence/nxs/main/install.sh | sh

# Login and use
nxs login --url http://localhost:8081 --user admin
nxs repo list
nxs push my-repo path/to/artifact.jar artifact.jar
nxs search --repo maven-releases --q mylib --json | jq '.[].version'

Full command reference and CI/CD examples: github.com/nexspence/nxs

---

Kubernetes (Helm)

Requirements: Helm 3.x, Kubernetes >= 1.26

cd deploy/helm/nexspence && helm dependency update
helm install nexspence \
  deploy/helm/nexspence \
  -f deploy/helm/nexspence/values-examples/nginx.yaml \
  --set config.jwtSecret="$(openssl rand -hex 32)" \
  --set config.adminPassword="changeme" \
  --namespace nexspence \
  --create-namespace

config.jwtSecret is optional — the chart auto-generates a unique secret (persisted across upgrades) when it is omitted. Set it only to pin a known value.

Five networking options (nginx, Traefik, Cilium ingress, Istio Gateway, Cilium Gateway API), external PostgreSQL, S3 storage, and HPA — see deploy/helm/nexspence/README.md.

---

Terraform Provider

Manage Nexspence as code with the official Terraform provider — repositories, blob stores, users, roles, content selectors, and privileges.

terraform {
  required_providers {
    nexspence = {
      source  = "nexspence/nexspence"
      version = "~> 0.2"
    }
  }
}

provider "nexspence" {
  url   = "https://nexspence.example.com"
  token = var.nexspence_token # nxs_* API token
}

resource "nexspence_repository" "maven_central" {
  name       = "maven-central"
  format     = "maven2"
  type       = "proxy"
  blob_store = "default"
  proxy {
    remote_url = "https://repo1.maven.org/maven2/"
  }
}

Published on the Terraform Registry — source at nexspence/terraform-provider-nexspence.

---

Supported Package Formats

Format	Hosted	Proxy	Group
Maven 2 / 3	✓	✓	✓
npm	✓	✓	✓
PyPI	✓	✓	✓
Go modules (GOPROXY v2)	✓	✓	✓
Docker	✓	✓	✓
OCI artifacts (Helm oci:// push, ORAS, cosign)	✓	✓	✓
NuGet v2 / v3	✓	✓	✓
Helm charts	✓	✓	✓
Cargo (Rust)	✓	✓	✓
Raw files	✓	✓	✓
APT (Debian/Ubuntu)	✓	✓	✓
Yum / RPM	✓	✓	✓
Conan (C/C++)	✓	✓	✓
Conda	✓	✓	✓
Terraform Registry	✓	✓	✓
RubyGems	✓	✓	—
R / CRAN	✓	✓	✓

---

Features

Repository Types

• Hosted — direct upload and storage
• Proxy — transparent remote caching; mutations rejected with 405
• Group — ordered union of hosted + proxy repos under one URL; index documents are merged across members, not shadowed by the first one that answers

OCI Registry

• One implementation serving two format labels: docker for container images, oci for Helm charts pushed with helm push oci://, ORAS artifacts and cosign signatures
• Referrers API (/v2/{name}/referrers/{digest}) with artifactType filtering — cosign signatures, SBOMs and in-toto attestations are discoverable
• Catalog and paginated tag listing; cross-repository blob mounts, access-checked against the source
• Artifact types recorded on push and on proxy cache-fill, and shown in the browse tree

Security & Auth

• Local accounts with JWT bearer tokens and bcrypt passwords
• LDAP / Active Directory — JIT provisioning, group-to-role mapping
• OIDC / OAuth2 SSO — Keycloak, Google, Entra ID, Okta; PKCE
• User API tokens (nxs_* prefix, SHA-256 hashed)
• RBAC — Roles, Privileges, Content Selectors (CEL expressions)

Storage

• Local filesystem (default), S3-compatible (AWS S3, MinIO, Ceph), or Azure Blob Storage
• Per-repository blob store routing; blob store groups (round-robin / write-to-first)
• Storage quotas per blob store and per repository

Operations

• High Availability — stateless nodes, Redis distributed locks, /healthz + /readyz
• Cleanup policies — by age, last-downloaded, retain-N-versions; cron scheduler; dry-run
• Per-repository export / import (streaming .tar.gz); full system backup / restore
• Live migration from a running Nexus instance — repositories, artifacts, container images, privileges/roles/users, routing rules; pausable, resumable, restart-safe (guide)
• Vulnerability scanning — OSV.dev for Maven/npm/PyPI/Cargo out of the box; Docker/OCI images with a Trivy you supply (setup)
• Audit log — every action logged; NDJSON streaming export; 90-day partition rotation
• Webhooks — HMAC-SHA256 signed; artifact.published, artifact.deleted, repo events
• Content Replication — push to remote instance on cron schedule
• Monitoring — Prometheus /metrics endpoint (Bearer-auth by default, anonymous with metrics.public); pre-built Grafana dashboard; ring-buffer history API; UI Charts + Repositories tabs

---

Documentation

Full documentation — deployment variants, HA setup, OIDC SSO, webhooks, the RBAC guide, the OpenAPI spec, and the architecture overview — lives on the website:

📖 nexspence.com/docs

The Helm chart reference ships with the chart itself: deploy/helm/nexspence/README.md.

---

Roadmap

Phase	Feature	Status
1–22	Core — repos, RBAC, formats, blob stores, proxy, group, cleanup	✓ complete
25–28	Audit log, Docker anon auth, OIDC/OAuth2 SSO	✓ complete
38–51	Live Nexus migration, sidebar collapse, S3 routing, blob store groups	✓ complete
53–55	High Availability, vulnerability dashboard, content replication	✓ complete
56	Staging & Build Promotion — CEL filter, scan gate, approval queue	✓ complete
60–63	LDAP role mapping, Conda, Terraform, Helm chart	✓ complete
64–67	Landing page, in-app docs, security hardening	✓ complete
68	Extended monitoring — Prometheus endpoint, Grafana dashboard, UI Charts tab	✓ complete
69	Blob GC — age-gated orphan collection, global cron scheduler, UI panel	✓ complete
70	OpenTelemetry tracing — spans across API, proxy and background jobs, trace_id in structured logs	✓ complete
CLI	nxs CLI — terminal & CI/CD client, v0.1.0	✓ complete
next	SBOM generation, cosign image signing	planned

---

Sponsors

Nexspence is free and AGPLv3 — no paid tier, no license fees, nothing behind a paywall. Sponsorship pays for the demo instance, the docs site, CI minutes and development time.

Tier	Price	Rewards
☕ Supporter	$5/mo	Sponsor badge · your name in SPONSORS.md · newsletter
🚀 Backer	$25/mo	+ your name and link in this README · a say in roadmap polls
🏢 Sponsor	$100/mo	+ your logo here and on nexspence.com · priority issue triage

No sponsors yet — be the first, your logo goes here.

Full list and details: SPONSORS.md

---

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

# Run backend tests
go test ./...

# Run frontend linter
cd frontend && npm run lint

---

License

AGPL-3.0-or-later — the full text is in LICENSE, the copyright and third-party notices in NOTICE.

AGPL rather than a permissive licence for one reason: Nexspence is a network service, and §13 is what keeps a hosted fork from being closed off. Running it inside your company, however you like, needs nothing from you — the obligation only starts if you offer a modified Nexspence to others over a network, and then it is to publish those modifications.

Contributions are accepted under the same licence, with no CLA and no sign-off to remember — see CONTRIBUTING.md.

Community & contact

Where	What for
💬 @nexspence_community	Telegram channel — release announcements, setup questions, roadmap talk
🐞 GitHub Issues	Bug reports and feature requests, tracked to a release
✉️ @skensel	Direct line to the maintainer — security reports, sponsorship, anything private

---