Backup, Restore, Configuration Export, Blob Recovery, Disaster Scenarios, and Recovery Validation: Concepts, Architecture, and Mental Model

1. The production question is not “Do we have backups?”

The meaningful question is: Can we restore the artifact service to a known point and prove it is correct? Nexus Repository stores durable state in more than one place. The database contains repository configuration, security/configuration metadata, and references to components/assets. Blob stores hold the repository bytes and storage-side metadata. External PostgreSQL, object storage, reverse proxies, DNS/TLS, and identity providers have their own recovery domains.

A successful copy job can therefore still produce an unusable restore. If the database is from 02:00 and the blob store is from 01:00, the database can refer to binaries that do not exist in restored storage. If the blob store is newer than the database, storage may contain artifacts the database does not know about. The recovery design must control, measure, and validate that relationship.

2. State map: what must be recoverable?

flowchart TB
  APP[Nexus application binaries
replaceable from trusted distribution]
  DATA[Nexus data directory]
  DB[(H2 or PostgreSQL
database/configuration metadata)]
  BLOB[(File/object blob stores
artifact bytes + storage metadata)]
  NODE[Node identity
$data-dir/keystores/node]
  CFG[Custom runtime/config files]
  EXT[External dependencies
DNS/TLS/IdP/reverse proxy]
  REC[Validated recovery set]
  DATA --> NODE
  DATA --> CFG
  DB --> REC
  BLOB --> REC
  NODE --> REC
  CFG --> REC
  APP --> REC
  EXT -. documented separately .-> REC

The application distribution is usually replaceable if you can obtain the exact trusted version again. The persistent state is not. Sonatype specifically calls out blob stores, database state, custom configuration, and the node-ID files. External dependencies are not magically contained in a Nexus database backup; a recovery runbook must name their owners and restoration prerequisites.

3. A consistency point is the heart of the recovery set

Think in terms of a logical transaction boundary. At time T, the database says which components/assets exist and where they live; the blob backup must preserve the corresponding bytes. Perfectly atomic cross-system snapshots are not always available, so operators use maintenance windows, read-only/frozen writes, storage snapshots, database-native backup features, or carefully bounded skew followed by supported reconciliation.

4. H2: convenient for small instances, but backup discipline still matters

For current H2-based instances, Nexus provides the Admin - Backup H2 Database task. Sonatype also recommends periodic offline backups of the embedded database files while Nexus is stopped because embedded-database backups taken while the server is running can be corruption-prone. The task backs up database state; it does not make your blob-store backup for you.

For an H2 restore, Sonatype instructs administrators to stop Nexus, restore the complete timestamp-matched database backup set, restore the corresponding blob-store backup, then restart and verify. This chapter never treats a lone nexus.mv.db file as a complete Nexus recovery set.

5. PostgreSQL: Nexus does not replace database-administrator backup tooling

With external PostgreSQL, there is no Nexus task equivalent to the H2 backup task. Use PostgreSQL-supported backup/recovery methods appropriate to your RPO/RTO—for example logical dumps for some cases, or physical/base backups and WAL-aware recovery strategies for larger production systems. The important Nexus-side requirement is that the recovered database point aligns with the recovered blob-store point.

Do not copy a live PostgreSQL data directory as a casual filesystem backup. Database-native tooling understands WAL, consistency, transaction boundaries, and restore requirements that a blind copy does not.

6. Blob stores are not rebuildable caches

A hosted repository’s blob content may be the only copy of an internally produced release. Proxy content may be re-fetchable in some cases, but upstream mutability, deletion, availability, routing rules, and compliance constraints mean “we can download it again” is not a recovery strategy. Back up every blob store according to its backend:

• File blob store: protect the configured directory using a consistent filesystem/storage backup method.
• S3/Azure/GCP/object storage: use provider-supported snapshot/versioning/replication/backup controls and document exact restore semantics.
• Blob-store groups/shared storage: record member topology and version/edition prerequisites; Chapter 28 revisits resilient/HA storage patterns.

Never modify the obfuscated internal blob files to “repair” a backup. Use supported recovery/reconciliation mechanisms.

7. Preserve node identity and custom configuration deliberately

Current Sonatype guidance requires backing up $data-dir/keystores/node/. That node ID affects restored blob metrics and Repository Firewall reporting. Also inventory custom configuration in the data and installation directories: runtime properties, trust material, keystores, logging overrides, and other environment-specific files. Secrets require special handling—encrypt backup media, restrict access, and avoid printing them into runbooks or support evidence.

8. Repository export/import is not full-instance backup/restore

Current repository export/import tasks are Nexus Repository Pro features intended for moving repository content. Import does not restore the entire Nexus server. Sonatype documents that import does not preserve server configuration or tags and regenerates metadata/checksums for imported content. That makes export/import useful for migration/content-transfer scenarios, but it is not a substitute for restoring database/configuration plus blob state.

9. RPO and RTO turn “backup” into an engineering requirement

Recovery Point Objective (RPO) is the maximum acceptable amount of data loss measured in time. If your RPO is 15 minutes, a nightly backup is structurally incapable of meeting it. Recovery Time Objective (RTO) is the target time to restore service. A 20 TB blob store copied over a 1 Gbit/s link may violate a two-hour RTO even if the backup itself is valid.

Use RPO/RTO to choose snapshot frequency, database method, storage replication, backup location, validation frequency, staffing, and runbook automation. Chapter 28 later separates these recovery objectives from high availability.

10. Recovery sequence: restore state, then prove service

1. Declare the incident and freeze further destructive changes.
2. Identify the target recovery point and exact Nexus version/database/blob topology.
3. Provision an isolated restore target with the expected runtime/version.
4. Restore database/configuration, blob stores, node ID, and required custom files according to documented procedure.
5. Start Nexus only when the restored state is coherent enough for the selected procedure.
6. Run supported reconciliation only when the evidence/procedure calls for it; do not run repair tasks as folklore.
7. Validate repository list, security/configuration, components/assets, byte hashes, and client requests.
8. Document residual gaps before promoting the restored service into use.

11. The validation ladder

A green process is not enough. Validate from coarse to specific:

1. Process: correct version/runtime starts without fatal errors.
2. Configuration: expected repositories, blob mappings, realms/roles, and routing settings exist.
3. Metadata: known components/assets are searchable/browsable.
4. Bytes: sample critical artifacts download and match pre-backup checksums/digests.
5. Authorization: a scoped test identity can read/write exactly what it should.
6. Client path: Maven/npm/Docker/etc. performs a controlled request through the restored endpoint.
7. Observability: logs/tasks/metrics show no unexplained database/blob errors.

12. Read-only preflight before you touch backup state

Record a recovery manifest. Example fixture:

{
  "capturedAt": "2026-08-27T00:30:00Z",
  "nexusVersion": "3.95.2-01",
  "java": "21",
  "database": {"type": "H2", "point": "backup-20260827T003000Z"},
  "blobStores": [{"name": "ch25-file", "point": "snapshot-20260827T003000Z"}],
  "nodeIdBackedUp": true,
  "rpoMinutes": 60,
  "rtoMinutes": 120
}

The manifest is not the backup itself. It is evidence describing exactly what the backup set claims to contain.

13. Mini-lab: prove why both halves matter

from pathlib import Path
import hashlib, json
root = Path('ch25-state'); root.mkdir(exist_ok=True)
blob = root/'artifact.bin'; blob.write_bytes(b'learner-example-1.0
')
sha = hashlib.sha256(blob.read_bytes()).hexdigest()
(root/'db.json').write_text(json.dumps({'asset':'artifact.bin','sha256':sha}, indent=2))
print('db points to:', sha)
print('blob actually:', hashlib.sha256(blob.read_bytes()).hexdigest())

Now imagine restoring db.json without artifact.bin: metadata exists, bytes do not. Imagine restoring the blob without the database: bytes exist but normal repository metadata cannot necessarily expose them. Real Nexus recovery has richer metadata, but the consistency principle is the same.

14. Knowledge check

15. Summary and bridge

Nexus recovery is a coordinated restoration of database/configuration, blob content, identity/config files, and surrounding dependencies to a declared point. RPO/RTO define the required service level; validation turns a backup claim into evidence. Lesson 2 now executes that model on disposable state and shows how to prove a recovery rather than merely complete a copy.

Official references and version notes

• Sonatype: Backup and Restore — embedded H2 backup-task behavior and the role of database snapshots.
• Sonatype: Prepare a Backup — blob-store, node-ID, database, and custom-configuration backup requirements.
• Sonatype: Configure the Backup Task — current H2 task name and the recommendation for periodic offline embedded-database backups.
• Sonatype: Restore an H2 Database — stop/restore/restart sequence and same-point blob-store requirement.
• Sonatype: Nexus Repository Database — H2/PostgreSQL boundaries and PostgreSQL backup responsibilities.
• PostgreSQL: Backup and Restore — database-native backup methods for external PostgreSQL.
• Sonatype: Storage Guide — blob-store layout and the warning not to modify internal blob files manually.
• Sonatype: Data Repair Tasks — current plan-based reconciliation for database/blob inconsistencies and supported formats.
• Sonatype: Repository Export — Pro-only content export and its operational limits.
• Sonatype: Repository Import — Pro-only content import, generated metadata, and what is not preserved.
• Sonatype: Backup/Same-Site Restore — RPO/RTO and test-restore expectations.
• Sonatype: Resiliency — recovery expectations after database failure and the distinction from HA.
• Sonatype: Nexus Repository 3.95.x Release Notes — dated version line used as the chapter reference.