Checkpoint Lab — Scheduled Tasks, Repair Jobs, Metadata Rebuilds, Blob Maintenance, and Operational Housekeeping

1. Checkpoint scenario

You operate a tiny internal Nexus instance used by a training CI system. The artifact repository is healthy, but the team has no maintenance calendar. A previous operator copied a weekly “repair everything” checklist from an old blog. Your job is to replace folklore with a controlled operating model.

You will:

1. create a dedicated Raw hosted repository and file blob store;
2. publish two tiny immutable evidence files;
3. create a safe H2 backup task;
4. create a safe file-blob temporary-file cleanup task;
5. intentionally fail a second backup execution using a disposable unwritable destination or synthetic fixture;
6. diagnose the failure from task history/logs;
7. prove repository content did not change;
8. produce a maintenance calendar and runbook.

2. Preflight and assumptions

Stop if the instance contains valuable data, if you cannot identify the data directory/database/blob store, or if another maintenance/migration/restore task is running.

3. Required predictions before mutation

Write these predictions in predictions.md before creating tasks:

1. Prediction A: a successful H2 backup run creates backup output and updates task history/log evidence, but does not change the two Raw artifact hashes.
2. Prediction B: a temporary-file cleanup on the dedicated file blob store may be a no-op; it should not delete normal repository assets.
3. Prediction C: an H2 backup directed to a safely unwritable lab destination should fail without changing repository artifact bytes.
4. Prediction D: no Repair task is required because the repository is healthy.

4. Create immutable evidence payloads

mkdir -p task-checkpoint-evidence
cd task-checkpoint-evidence
printf 'checkpoint artifact alpha\n' > alpha.txt
printf 'checkpoint artifact beta\n' > beta.txt
sha256sum alpha.txt beta.txt | tee expected-sha256.txt

Upload them to:

learner-example/task-checkpoint/1.0.0/alpha.txt
learner-example/task-checkpoint/1.0.0/beta.txt

Verify by fresh HTTP requests and save the downloaded hashes in before-sha256.txt. This is your independent consistency baseline.

5. Capture task inventory before changes

Save either a screenshot/export or a manually transcribed table of task name, type, enabled state, schedule, next run, last run, and result. If using the list API with a least-privilege observer, save the JSON as tasks-before.json. Redact credentials and internal secrets.

6. Configure Task A — H2 backup

Create Admin - Backup H2 Database:

Name: LAB19 - H2 backup - checkpoint
Frequency: Manual for first validation
Location: <dedicated writable relative lab path>
Notification: optional; do not require external SMTP for the lab

Run it once. Capture result, task log, backup directory listing, and output size. Then verify alpha/beta again. Prediction A should hold.

7. Configure Task B — delete blobstore temporary files

Create Admin - Delete blobstore temporary files for task-checkpoint-blobs if present in your version. Ensure no upload is in progress. Run it once manually and capture the task result/log.

Do not create fake temporary blob files in Nexus internals. A zero-deletion run is acceptable and preferable to unsupported mutation. Verify alpha/beta again. Prediction B should hold.

8. Failure injection — backup destination denied

Choose one of two paths:

Path A — live safe failure

If your disposable deployment lets you identify a safely isolated directory resolved by the H2 task's relative Location field, create a lab-only subdirectory there and deny the Nexus process identity write permission. Point a copied/manual H2 backup task to that relative location and run it. Do not change permissions on the Nexus application directory, database files, blob stores, or unrelated data-directory content. If that isolation is not clear, use Path B instead.

Path B — simulation when safe permission control is impractical

Use this fixture and treat it as the task log for diagnosis:

Task: LAB19 - H2 backup - denied
Type: h2.backup.task
State: WAITING
Last result: FAILURE
Message: java.nio.file.AccessDeniedException: /lab/denied
Timestamp: 2026-08-26T03:10:14+04:00

Prediction C is about state separation: a failed backup output path should not mutate artifact bytes.

9. Diagnose the failure

1. Preserve the failed task configuration and log.
2. Confirm the task type and Nexus version.
3. Confirm H2 database assumption; do not apply this task to PostgreSQL.
4. Inspect the destination path and Nexus process identity.
5. Check free disk and file permissions.
6. Confirm no unrelated task failed at the same time.
7. Correct only the lab backup destination/permissions.
8. Rerun the backup task and verify success.
9. Re-download alpha/beta and compare SHA-256 hashes.

Document why the least-destructive correction was changing the destination permissions, not restarting as root or editing Nexus internals.

10. Build the maintenance calendar

Create maintenance-calendar.md with a table like this, using your measured durations rather than copying these exact times:

11. Task authorization matrix

Create task-authz.md:

12. Prove repository content remained consistent

curl -fsS -o alpha-after.txt \
  'http://127.0.0.1:8081/repository/task-checkpoint-raw/learner-example/task-checkpoint/1.0.0/alpha.txt'
curl -fsS -o beta-after.txt \
  'http://127.0.0.1:8081/repository/task-checkpoint-raw/learner-example/task-checkpoint/1.0.0/beta.txt'
sha256sum alpha-after.txt beta-after.txt | tee after-sha256.txt

Compare against the original hashes. Also verify the assets in Browse and, if available, Search. If search differs but exact downloads and hashes are correct, do not jump to blob recovery; diagnose the derived index layer.

13. Required evidence packet

14. Checkpoint runbook

Your runbook must explain:

1. how to identify the exact task type in the current version;
2. how to prove no conflicting maintenance is running;
3. how to record task-specific scope and expected mutation;
4. which task logs and Nexus logs to preserve;
5. how to verify repository content independently;
6. when cancellation is unsafe or incomplete;
7. why Repair tasks are incident-driven;
8. how to detect stale task names after upgrades;
9. how to restore a failed task to a known-good schedule;
10. how Chapter 20 automation will inspect state before changing it.

15. Cleanup and rollback

1. Restore permissions on any lab-only failure directory, then remove it.
2. Return lab tasks to Manual/disabled or delete only the lab-created task definitions through supported UI controls.
3. Delete task-checkpoint-raw through Nexus.
4. Delete task-checkpoint-blobs only after Nexus confirms it is unused.
5. Remove temporary observer/runner users and credentials.
6. Keep the evidence packet outside the disposable Nexus data directory.
7. Do not delete internal task rows, H2 files, blob files, or logs needed for unresolved incidents.

16. Knowledge check

17. Chapter checkpoint summary

You can now operate Nexus tasks as controlled maintenance jobs rather than mysterious buttons: inventory current task types, separate routine work from repair, schedule against real resource windows, use least privilege, preserve task logs, diagnose failures without escalation, and independently verify repository state. Chapter 20 builds on this discipline by automating repository and security operations through documented REST APIs and idempotent infrastructure-as-code patterns.

Official references and version notes

• Sonatype: Tasks — task states, schedules, logs, current task catalog, and Repair-task cautions.
• Sonatype: Tasks API — list/get/run/stop operations and Pro-only create/update/delete/template endpoints.
• Sonatype: Data Repair Tasks — current plan/execute workflow and recovery-only use.
• Sonatype: Cleanup Policies — cleanup-system tasks, soft deletion, and compact-blob-store reclamation.
• Sonatype: Privileges — nx-tasks-read, nx-tasks-run, create/update/delete task privileges, and least-privilege design.
• Sonatype: Nexus Repository 3.95.0–3.95.2 Release Notes — dated feature and maintenance-task changes.
• Sonatype: System Requirements — Java 21, database guidance, storage, and capacity prerequisites.
• Sonatype: Backup and Restore — recovery context for backup tasks.