metadb: add optional fast restart path that skips storage walk when (version + commit + storage config) matches metaDB stamp (#4026)

* chore(metadb): add writer version to interface Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(metadb): add writer version to db mock Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(metadb): implement writer version for bolt, redis, and dynamodb Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * feat(metadb): add optional fast restart path that skips storage walk when binary identity matches metaDB stamp binary identity is determined by the current release tag/commit and stored in metaDB after a successful storage parse. When fast restart is enabled, the next startup will skip the parse if the stored identity matches the current binary Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(cli): serve: add a way to force reparse storage Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * refactor(meta): version: split to avoid global state mutation in tests Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): version: include commit in writerVersion to distinguish retags Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(config): add IsFastRestartEnabled() test Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): skip writer-version stamp when storage parse is incomplete ParseStorage returns nil even when individual repos fail to parse or are only partially parsed (a missing manifest blob), so MaybeParseStorage would stamp a partially-populated metaDB as good. On the next restart fastRestart trusts the stamp, skips the storage walk, and never recovers. Track per-repo outcomes via parseStats and stamp only when the walk fully populated the metaDB, otherwise log and continue so the next restart reparses Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(docs): readme: remove trailing comma from JSON config Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): dynamodb: use context.Background instead of context.TODO Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(meta): invalidate fast restart on storage config changes Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore(meta): dynamodb: use context.Background() instead of context.TODO() Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * docs(meta): dynamodb: add comment about nil AttributeValue handling in GetWriterVersion Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * chore: rename writer-version stamp to fast-restart stamp also replaces the version/commit tracking to use BinaryVersion instead of WriterVersion This should make things more clear Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(config): ensure FastRestart is on GlobalStorageConfig This is not a per-subpath setting Signed-off-by: Jacob McSwain <jacob@mcswain.dev> * fix(metadb): redis: tests: ensure clients are closed Signed-off-by: Jacob McSwain <jacob@mcswain.dev> --------- Signed-off-by: Jacob McSwain <jacob@mcswain.dev>
2026-06-17 21:17:58 +08:00 · 2026-06-09 12:47:20 -05:00
parent d480380ef7
commit 273b15364b
19 changed files with 1103 additions and 44 deletions
@@ -35,6 +35,7 @@ Examples of working configurations for various use cases are available [here](..
  - [Top-level Configuration Map](#top-level-configuration-map)
  - [Network](#network)
  - [Storage](#storage)
+    - [Fast restart](#fast-restart)
  - [Authentication](#authentication)
    - [TLS Mutual Authentication](#tls-mutual-authentication)
    - [Passphrase Authentication](#passphrase-authentication)
@@ -167,6 +168,33 @@ their own repository paths, dedupe and garbage collection settings with:
    },
 ```

+### Fast restart
+
+On large registries (for example a 1TB+ S3 backend with many repos), the
+startup walk that reconciles metaDB with the current storage can dominate
+restart time. Setting `fastRestart` lets zot skip that walk when the same
+binary is restarted with the same storage config. After a successful walk,
+zot stamps metaDB with the running binary's identity plus a fingerprint of
+the storage config, so that the next startup, if the stamp matches, may skip
+the walk. Any binary upgrade or storage configuration changes (for example,
+`dedupe`/`rootDirectory`/`subPaths`) invalidates the stamp and forces a full
+reparse.
+
+Fast restart is off by default. The trade-off when enabling it is that
+out-of-band changes to Zot's storage will not be detected and may cause
+inconsistencies between the metaDB and storage. To enable it:
+
+```json
+    "storage": {
+        "rootDirectory": "/var/lib/registry",
+        "fastRestart": true
+    }
+```
+
+`fastRestart` is a top-level storage setting; it is not honored under `subPaths`.
+
+You can also force a full reparse with the `--force-reparse` flag to `zot serve`.
+
 ## Retention

 You can define tag retention rules that govern how many tags of a given repository to retain, or for how long to retain certain tags.