fix(#10536): the server seeds an empty configuration directory with the shipped defaults at startup - #10555

Closes #10536

Summary

A configuration directory moved off <root>/config (arcadedb.server.configDirectory pointing at a Kubernetes PersistentVolumeClaim, which is never populated from the image) started empty. The server then ran on its built-in groups, which have no readonly group, and Gremlin started from TinkerPop's bare Settings. The plain StatefulSet worked around it with an init container running /bin/sh, which the native images (scratch, distroless) do not have. That manifest was removed in #10542, and this PR implements the issue's suggested fix: the server seeds the directory itself at startup, from the <root>/config of the image it runs. It needs no shell and no second image reference, so it cannot copy another version's defaults.

• ConfigDirectorySeeder copies server-groups.json, gremlin-server.yaml, gremlin-server.groovy and gremlin-server.properties. It runs in ArcadeDBServer.startInternal(), before security, the AI and support configurations and the plugins read the directory.
• The seed is all or nothing: files are staged in a sub-directory and moved into place only once every copy succeeded, so a failure cannot leave a half-seeded directory that is never seeded again.
• Only a directory that holds no regular file yet is seeded (missing, empty, or holding only a lost+found directory). From then on, what is in it or missing from it is the operator's: an edit is never overwritten and a file deleted on purpose does not come back.
• Only the shipped defaults are copied. Users, API tokens or a server-configuration.json left under <root>/config by a server that ran there are not carried over.
• The logging files are not seeded (the issue's second note): the JVM loads them through -Djava.util.logging.config.file, never from the configuration directory.
• A failure is logged as a WARNING, and the server starts on its built-in defaults as before.
• PackagingManifestsTest now requires every file under package/src/main/config to be either seeded or excluded with a reason, so a new shipped default cannot be forgotten.

Finding ledger

• 1. The seed needs /bin/sh, which the native images lack: fixed, the server seeds without a shell.
• 2. The seed copies arcadedb-log*.properties, which is not read from the configuration directory: fixed, not seeded, pinned by PackagingManifestsTest.
• 3. Persisting configDirectory was safe only together with readinessRequiresHA=true, and that was not documented: the manifest it applied to is gone (chore(k8s): remove the plain StatefulSet example, the Helm chart is the only Kubernetes deployment #10542). For the Helm chart, the only Kubernetes deployment now, this is tracked in Parity with the core repo's retired Kubernetes example: backup directory, HA readiness default, native-safe config seeding arcadedb-helm#42 (item 4).

Test plan

• Issue10536ConfigDirectorySeedTest (8 tests, including a seed that fails halfway and leaves no file behind): a started server seeds an empty moved directory byte for byte, and the security in force has the readonly group (red before the fix, when the server wrote its built-in groups instead); a directory in use is left alone; a deleted default stays deleted; a volume holding only lost+found is seeded; stale users, tokens and settings under <root>/config are not copied; the default (unmoved) directory and an embedded server with no shipped config are untouched.
• PackagingManifestsTest.everyShippedConfigFileIsSeededIntoAMovedConfigDirectoryOrExcludedForAReason, checked to fail when an unplaced file is added to package/src/main/config.
• Regression: mvn -o -pl server test -Dtest='*Security*Test,*Config*Test,*Group*Test,ServerConfigurationIT': 402 tests, 0 failures. Issue7415ConfigDirectoryTest, UnstartedServerTest: green.

Coverage

Invariant: a server whose configuration directory starts empty runs with the defaults its own image ships, on every image.

Sweep:

$ git grep -n "startInternal()" -- "*/src/main/java/*"
server/src/main/java/com/arcadedb/server/ArcadeDBServer.java:543:      startInternal();      <- the only caller, from start()
$ git grep -n "serverConfigPath" server/src/main/java/com/arcadedb/server/ArcadeDBServer.java
359, 375: resolved in both constructors
595: ConfigDirectorySeeder.seed(...)      <- new
658: new ServerSecurity(...)  672: InstanceIdResolver  682: AiConfiguration  686: SupportService
2792: loadConfiguration() (constructor, reads server-configuration.json, which is never seeded)
$ git grep -n "getConfigPath()" -- "*/src/main/java/*"
GremlinServerPlugin:93, MCPPlugin:74, ServerControlPlane:1746/1777/2067, AutoBackupSchedulerPlugin:65/363   <- plugins/handlers, all after startInternal() line 595

Known gaps

• A volume mounted over <root>/config (the image's VOLUME path, and the Helm chart's layout today) hides the shipped files, so there is nothing to seed from. Filed as A volume mounted over <root>/config is not seeded with the shipped defaults, because they are read from that same directory #10554 (bundle the defaults as resources). The workaround is to mount the volume elsewhere and set arcadedb.server.configDirectory.

Residual risk

• The defaults a later image adds or changes do not reach a directory that is already in use. This is deliberate: the alternative brings back files an operator deleted. Merge the changed defaults by hand after an upgrade.
• The seed reads <root>/config, so the case in A volume mounted over <root>/config is not seeded with the shipped defaults, because they are read from that same directory #10554 is not covered.

Adversarial pass

• A volume mounted over <root>/config hides the shipped files, so nothing is seeded: real, out of scope, filed as A volume mounted over <root>/config is not seeded with the shipped defaults, because they are read from that same directory #10554.
• Seeding copied every missing file on every start, so a file deleted on purpose came back: real, fixed here. Only a directory with no regular file is seeded (as the issue suggested), with lost+found tolerated. Tests aDefaultDeletedOnPurposeIsNotBroughtBackOnTheNextStart, aFreshVolumeHoldingOnlyLostAndFoundIsSeeded.
• The issue's readinessRequiresHA note is not recorded in this repo: the manifest it applied to was removed in chore(k8s): remove the plain StatefulSet example, the Helm chart is the only Kubernetes deployment #10542, and it is tracked for the Helm chart in Parity with the core repo's retired Kubernetes example: backup directory, HA readiness default, native-safe config seeding arcadedb-helm#42.

Review cycles

• cycle 1, dff0f39: initial fix. The claude review flagged that a seed failing halfway is never repaired (1), plus import order and overload naming (4), and a missing failure test (5). Also symlinks (3).
• cycle 2, 7266953: seed made all or nothing through a staging directory, seedFromRoot renamed, imports sorted, failure test added. Claude review: LGTM, four non-blocking suggestions.

Deferred items

• Cycle 1 (3), symlinks followed under <root>/config: skipped. The source is the image's own config directory, so following a link there is intended.
• Cycle 2 (1), several servers starting on one shared directory can mix seeded files: skipped, since each node has its own directory in every supported layout. Each file is still either the shipped one or the other writer's, never a partial file.
• Cycle 2 (2), a FINE log when configDirectory is a regular file: skipped, because the server fails on that path elsewhere with its own error.
• Cycle 2 (3), document symlink following: skipped, same reason as cycle 1 (3).
• Cycle 2 (4), split the half-failure test: skipped. The steps are one scenario (fail, no leftovers, recover) and each assertion carries its own message.

Final state

clean-approval (LGTM on 7266953, remaining suggestions non-blocking and recorded above).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Empty or relocated configuration directories are automatically populated with the shipped server configuration files during startup.
  • Existing configuration files are preserved, and only supported default configuration files are copied.
  • Servers can start with the shipped security policy when using an empty configuration volume.

• Bug Fixes

  • Improved startup handling for empty, partially populated, or lost+found-only configuration directories.
  • Configuration seeding failures no longer prevent server startup; built-in defaults remain available.