Nexspence Documentation

Guides, configuration reference, and versioned changelog for Nexspence — the free, open-source universal artifact repository manager and drop-in alternative to Sonatype Nexus.

Nexspence manages Maven, npm, PyPI, Docker, Go modules, NuGet, Cargo, Helm, Apt, Yum/RPM, Conan, Raw, Conda and Terraform artifacts from a single self-hosted registry. Repositories can be Hosted (your published artifacts), Proxy (cached remote registries) or Group (multiple repositories under one URL).

This documentation covers Quick Start, Installation, Repositories, per-format guides, Browse & Search, Users, Roles & Privileges (RBAC), Cleanup policies, Webhooks, Migration from Nexus, Monitoring, Build Promotion, Replication, and the full REST API reference.

Get started in under two minutes with Docker Compose: download the latest release, set a strong admin_password and jwt_secret in config.yaml, then run docker compose up -d and open the UI at http://localhost:8081.

Format	URL pattern	Notes
Maven	`/repository/{name}/`	Use as `<url>` in `pom.xml` or `settings.xml`
npm	`/repository/{name}/`	Use as `registry` in `.npmrc`
PyPI	`/repository/{name}/simple/`	Use as `index-url` in `pip.conf`
Docker	`localhost:5000/{name}`	Registry port 5000, image name includes repo
Helm	`/repository/{name}/`	Add with `helm repo add`
Go	`/repository/{name}/`	Set as `GOPROXY`
NuGet	`/repository/{name}/index.json`	v3 flat container endpoint
Cargo	`/repository/{name}/`	Sparse index endpoint
Raw	`/repository/{name}/`	PUT/GET any path

What it matches	CEL expression
All Maven artifacts	`format == "maven2"`
Specific Maven group	`format == "maven2" && path.startsWith("/com/example/")`
All Docker images	`format == "docker"`
Specific repository	`repository == "npm-releases"`
All npm packages	`format == "npm"`
PyPI in specific repo	`format == "pypi" && repository == "pypi-releases"`
Exclude snapshots	`format == "maven2" && !path.contains("SNAPSHOT")`

Criterion	Description
Published before	Remove artifacts published more than N days ago.
Last downloaded before	Remove artifacts not downloaded in the last N days.
Retain N versions	Keep only the N newest versions of each component. All older versions are eligible for removal.

Event	When
`artifact.published`	Artifact pushed to hosted or cached by proxy
`artifact.deleted`	Artifact deleted
`repo.created`	Repository created
`repo.updated`	Repository configuration updated
`repo.deleted`	Repository deleted
`proxy.error`	Proxy failed to fetch from upstream

Item	Detail
Repositories	Hosted, proxy, and group repo definitions (format, type, configuration)
Users & Roles	Local Nexus users, roles, and privileges
Artifacts	All components streamed via Nexus REST API — large repos pause/resume
Cleanup policies	Imported and attached to the corresponding repositories

Metric	Description
`nexspence_requests_total`	Total HTTP requests (by method, path, status)
`nexspence_request_duration_seconds`	Request latency histogram (p50, p95, p99)
`nexspence_artifacts_total`	Total artifacts stored
`nexspence_bytes_stored_bytes`	Total storage used in bytes
`nexspence_downloads_total`	Total artifact downloads
`nexspence_artifacts_deleted_total`	Total artifacts deleted
`nexspence_goroutines`	Active Go goroutines
`nexspence_memory_alloc_bytes`	Heap memory in use

Service	URL	Default credentials
Web UI & REST API	`http://localhost:8081`	`admin / admin123`
Docker registry	`localhost:5000`	same
PostgreSQL	`localhost:5437`	`nexspence / nexspence`
MinIO console	`http://localhost:9001`	`minioadmin / minioadmin`

Key	Default	Description
`auth.jwt_secret`	—	Required. JWT signing key — min 32 chars
`bootstrap.admin_password`	`admin123`	Change before production. Auto-created admin password
`http.addr`	`:8081`	Listen address
`http.base_url`	`http://localhost:8081`	Public URL used in download links
`auth.jwt_expiry_hours`	`24`	JWT token lifetime
`auth.token_max_days`	`180`	Max lifetime for user API tokens (`nxs_*`)
`auth.anonymous_enabled`	`true`	Allow unauthenticated read on public repos
`storage.default_type`	`local`	`local` or `s3`
`storage.s3.endpoint`	—	S3 endpoint URL (e.g. `http://minio:9000`)
`storage.s3.bucket`	—	S3 bucket name (required when type=s3)
`storage.s3.force_path_style`	`true`	Required for MinIO / non-AWS S3
`redis.enabled`	`false`	Enable Redis (required for HA)
`redis.addr`	`localhost:6379`	Redis address
`cleanup.default_schedule`	`0 2 * * *`	Default cron for cleanup policies
`audit.retention_days`	`90`	Audit log partition retention

Format	Protocol	Hosted	Proxy	Group
Maven 2/3	Maven HTTP	✓	✓	✓
npm	npm registry v1	✓	✓	✓
PyPI	Simple index + twine	✓	✓	✓
Docker / OCI	OCI Distribution v2	✓	✓	✓
Go Modules	GOPROXY v2	✓	✓	✓
NuGet	v2 OData + v3 flat	✓	✓	✓
Helm	chart index.yaml	✓	✓	✓
Cargo	Sparse index	✓	✓	✓
Apt	Debian Packages index	✓	✓	✓
Yum / RPM	repomd.xml	✓	✓	✓
Conan	Conan v1	✓	✓	✓
Raw	HTTP PUT/GET	✓	✓	✓
Conda	conda index	✓	✓	✓
Terraform	Registry protocol v1	✓	✓	✓

Base Path	Purpose
`/service/rest/v1/`	Nexus OSS v1 REST API — 100% compatible, drop-in for existing pipelines
`/service/rest/beta/`	Nexus beta endpoints — partial support
`/api/v1/`	Native Nexspence API — migration, extended system info, monitoring
`/repository/:name/*`	Artifact protocol endpoints (Maven, npm, Docker, etc.)
`/v2/`	Docker OCI Distribution Spec v2

Docs & Changelog