feat!: allow a custom database data root

- Validate safe host-wide roots during guided and direct initialization
- Reject bind source changes to prevent silent database data moves

BREAKING CHANGE: `host.data_root` is now required in `config.yml`.

Author: evannotfound

openspec/changes/customize-database-root/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-20

openspec/changes/customize-database-root/design.md

@@ -0,0 +1,60 @@
+## Context
+
+`Paths.databases` currently fixes database files under `<state>/databases`, and `Database.data` derives
+every engine bind source from it. Generated assets, backup staging, and locks also derive from `Paths`,
+but they must remain in the canonical state tree when database files move to dedicated storage.
+
+The source configuration is strict and human-owned. evdb does not retain configuration history or move
+database data, while generated Compose already records the last bind source used for each managed role.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Store one explicit host-wide data root and use it for every database role.
+- Make fresh guided and direct setup support a mounted-disk directory.
+- Reject unsafe roots and prevent an existing generated role from silently switching to an empty path.
+- Keep the canonical root as the setup default.
+
+**Non-Goals:**
+
+- No per-project or per-role data paths.
+- No mount creation, persistence, startup ordering, or availability monitoring.
+- No data copy, relocation, import, compatibility default, or source migration.
+- No change to generated assets, backup staging, locks, or repositories.
+
+## Decisions
+
+### Put the root on Host and keep Paths as the canonical default
+
+Add required `Host.data_root: Path` and serialize it as `host.data_root`. `Database.data` uses this field,
+while `Paths.databases` remains the default selected by fresh initialization. This keeps operator policy
+in source configuration without making all runtime paths configurable.
+
+### Validate a dedicated safe directory
+
+The value must be a normalized absolute path with no symlinked or non-directory existing component. It
+must not be a broad filesystem ancestor or overlap evdb configuration, generated assets, Traefik,
+backups, locks, or a local Restic repository. For a custom root, the immediate parent must already exist;
+initialization creates or converges only the selected leaf as a private managed directory.
+
+The setup review states the selected path. The operator is responsible for mounting storage before evdb
+or Docker starts; evdb does not imply that a custom directory is a persistent mount.
+
+### Treat the root as immutable after role generation
+
+Fresh setup and source loading require the field. Existing-host initialization accepts only the stored
+value. Before replacing an existing role Compose file, database rendering compares the current primary
+data bind with the desired bind. A different source fails before creating the new data directory or
+rewriting Compose. This catches both supported command misuse and direct source edits without adding a
+machine-state file.
+
+## Risks / Trade-offs
+
+- [A configured disk is not mounted when Docker starts] -> State clearly that mounts and startup ordering
+  are operator-managed; evdb validates the directory but does not claim mount availability.
+- [A source edit points at an empty directory] -> Compare the generated primary data bind before any
+  render mutation and reject a changed source.
+- [Existing source lacks the required field] -> Reject it under the existing strict-schema policy; the
+  operator must provide current source explicitly.
+- [Generated Compose is absent] -> Allow rendering because no prior managed bind exists to preserve.

openspec/changes/customize-database-root/proposal.md

@@ -0,0 +1,35 @@
+## Why
+
+Database files are fixed under `/var/lib/evdb/databases`, which prevents an operator from placing them
+on a dedicated mounted disk during host setup. The host needs one explicit storage root while preserving
+the existing project and role layout.
+
+## What Changes
+
+- **BREAKING**: require `host.data_root` in `config.yml`; fresh setup writes
+  `/var/lib/evdb/databases` by default.
+- Add guided and direct initialization input for one host-wide database data root.
+- Derive every database bind source as `<data_root>/<project>/<role>/data`.
+- Validate the selected root as a safe normalized absolute path and reject overlap with other managed or
+  local repository paths.
+- Reject a changed data bind source when an existing generated Compose file records another root. evdb
+  does not move database data.
+- Keep mount configuration and startup ordering under operator control.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `config`: Make the host database data root explicit, safe, and immutable after database generation.
+- `host-setup`: Collect and prepare the host-wide database data root during initialization.
+- `deploy`: Allow database data outside `/var/lib/evdb` while keeping all other production paths fixed.
+
+## Impact
+
+This changes the host source schema, initialization CLI and review, database path derivation, generated
+Compose safety checks, documentation, and focused configuration and database tests. It adds no runtime
+dependency and does not change backup staging or repositories.

openspec/changes/customize-database-root/specs/config/spec.md

@@ -0,0 +1,47 @@
+## ADDED Requirements
+
+### Requirement: Database data root safety and immutability
+`host.data_root` SHALL be a normalized absolute non-symlink path for one dedicated evdb database tree.
+It SHALL NOT overlap source, generated assets, Traefik assets, backups, locks, or a local Restic
+repository. A custom root's immediate parent SHALL already exist and be safe. evdb SHALL reject a desired
+database bind source that differs from the source recorded in an existing generated role Compose file,
+and SHALL NOT move database data.
+
+#### Scenario: Custom root uses mounted storage
+- **WHEN** `host.data_root` is `/mnt/database-volume/evdb`
+- **THEN** project `example-prod-01` Postgres data resolves to `/mnt/database-volume/evdb/example-prod-01/postgres/data`
+
+#### Scenario: Root overlaps backup storage
+- **WHEN** `host.data_root` is equal to or contains the managed backup path
+- **THEN** validation fails before source, directories, or services change
+
+#### Scenario: Existing generated bind differs
+- **WHEN** a role's generated Compose file records a data bind under one root and source selects another
+- **THEN** rendering fails before creating the new data directory or replacing Compose
+
+## MODIFIED Requirements
+
+### Requirement: Canonical host paths
+Non-secret source SHALL live at `/etc/evdb/config.yml` and secret source at `/etc/evdb/secrets.yml`.
+An rclone repository SHALL reference one private native rclone file in place; a local repository SHALL
+omit `host.backup.rclone_config`. Generated database assets SHALL live under
+`/var/lib/evdb/projects/<project>/<role>`, dedicated Traefik assets under `/var/lib/evdb/traefik`, and
+mutable local backups and locks under `/var/lib/evdb`. Database data SHALL live under the required
+`host.data_root` using `<project>/<role>/data`; fresh initialization SHALL default that root to
+`/var/lib/evdb/databases` and write it explicitly.
+
+#### Scenario: Default Postgres paths are derived
+- **WHEN** fresh setup creates project `example-prod-01` with a Postgres role using the default data root
+- **THEN** its Compose path is `/var/lib/evdb/projects/example-prod-01/postgres/compose.yaml` and its data path is `/var/lib/evdb/databases/example-prod-01/postgres/data`
+
+#### Scenario: Custom Postgres data path is derived
+- **WHEN** `host.data_root` is `/mnt/database-volume/evdb` and project `example-prod-01` has a Postgres role
+- **THEN** its data path is `/mnt/database-volume/evdb/example-prod-01/postgres/data` while its Compose path remains canonical
+
+#### Scenario: Local repository is configured
+- **WHEN** `host.backup.repository` is a normalized absolute local path
+- **THEN** `config.yml` contains no rclone configuration field
+
+#### Scenario: Operator locates host inputs
+- **WHEN** an operator reviews `/etc/evdb`, `/var/lib/evdb`, and `host.data_root`
+- **THEN** evdb's desired settings and managed credentials are separated from generated runtime and database data

openspec/changes/customize-database-root/specs/deploy/spec.md

@@ -0,0 +1,12 @@
+## MODIFIED Requirements
+
+### Requirement: Production paths
+Canonical evdb source SHALL live under `/etc/evdb`; generated services, Traefik assets, local backups,
+and locks SHALL live under `/var/lib/evdb`; database data SHALL live under the explicitly configured
+`host.data_root`; and the verified tool SHALL be the regular executable `/usr/local/bin/evdb`. No copied
+rclone file, deployment machine state, activity record, restore staging, or transaction tree SHALL be
+created.
+
+#### Scenario: Tool version changes
+- **WHEN** the verified installer atomically replaces `/usr/local/bin/evdb`
+- **THEN** every database continues using stable source, generated, credential, backup, and configured data paths

openspec/changes/customize-database-root/specs/host-setup/spec.md

@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Host database root selection
+Fresh guided initialization SHALL ask for one host-wide database data root and default it to
+`/var/lib/evdb/databases`. Direct initialization SHALL accept `--data-root PATH`. The redacted review
+SHALL show the selected root, and initialization SHALL prepare it before database roles are rendered.
+evdb SHALL leave filesystem mounting and startup ordering to the operator.
+
+#### Scenario: Guided setup accepts the default
+- **WHEN** the operator accepts the database data root default
+- **THEN** source records `host.data_root: /var/lib/evdb/databases`
+
+#### Scenario: Guided setup selects a mounted-disk directory
+- **WHEN** the operator enters `/mnt/database-volume/evdb` whose immediate parent is safe and present
+- **THEN** review shows that path and initialization prepares it as the host database root
+
+#### Scenario: Source omits the data root
+- **WHEN** initialization loads `config.yml` without `host.data_root`
+- **THEN** it rejects the unsupported source instead of synthesizing a compatibility default

openspec/changes/customize-database-root/tasks.md

@@ -0,0 +1,11 @@
+## 1. Host Configuration
+
+- [x] 1.1 Add the required host data root to source loading, validation, serialization, guided setup, direct initialization, and review.
+
+## 2. Database Storage
+
+- [x] 2.1 Derive database paths and managed directories from the configured root, and reject changes that conflict with an existing generated Compose bind.
+
+## 3. Verification
+
+- [x] 3.1 Cover default, custom, unsafe, missing, and immutable-root behavior with focused tests and validate the change artifacts.

src/evdb/cli.py

@@ -12,11 +12,13 @@
     load,
     rclone_remotes,
     repository_parts,
+    validate_data_root,
     validate_domain,
     validate_email,
     validate_host_id,
 )
 from .errors import Error
+from .models import Paths
 from .run import clean
 
 
@@ -40,6 +42,11 @@ def parser() -> argparse.ArgumentParser:
     init = commands.add_parser("init", help="initialize or refresh this host")
     init.add_argument("--host-id", metavar="NAME", help="lowercase host name, e.g. example-01")
     init.add_argument("--domain", metavar="DOMAIN", help="base domain, e.g. storage.example.com")
+    init.add_argument(
+        "--data-root",
+        metavar="PATH",
+        help="absolute host-wide database data root",
+    )
     init.add_argument("--acme-email", metavar="EMAIL", help="ACME account email")
     init.add_argument("--dns-provider", metavar="PROVIDER", help="cataloged lego provider code")
     init.add_argument(
@@ -135,6 +142,7 @@ def main(
                 for name in (
                     "host_id",
                     "domain",
+                    "data_root",
                     "acme_email",
                     "dns_provider",
                     "repository",
@@ -322,7 +330,6 @@ def _init_values(
         try:
             if source is not None:
                 from .host import _initial
-                from .models import Paths
 
                 _initial(result, Paths(config=source.parent))
         except Error as exc:
@@ -369,6 +376,12 @@ def _init_host(result: dict, input_fn, output) -> None:
             "DNS zone used for database hostnames; example: storage.example.com",
             validate_domain,
         ),
+        (
+            "data_root",
+            "Database data root",
+            "Dedicated directory for all database files; mount storage before Apply.",
+            lambda value: str(validate_data_root(value)),
+        ),
         (
             "acme_email",
             "ACME email",
@@ -385,6 +398,7 @@ def _init_host(result: dict, input_fn, output) -> None:
             label,
             help_text=help_text,
             validate=validate,
+            default=str(Paths().databases) if name == "data_root" else None,
         )
         if value is None:
             raise KeyboardInterrupt
@@ -550,6 +564,7 @@ def _init_review(result: dict) -> str:
         {
             "Host": result["host_id"],
             "Base domain": result["domain"],
+            "Database data root": result["data_root"],
             "Wildcard": f"*.{result['host_id']}.{result['domain']}",
             "ACME email": result["acme_email"],
             "DNS provider": result["dns_provider"],
@@ -569,10 +584,11 @@ def _edit_init(result: dict, input_fn, output) -> None:
     fields = (
         ("1", "Host ID", ("host_id",)),
         ("2", "Base domain", ("domain",)),
-        ("3", "ACME email", ("acme_email",)),
-        ("4", "DNS provider and credentials", ("dns_provider", "dns", "dns_file")),
-        ("5", "Backup repository", ("repository", "rclone_config")),
-        ("6", "Restic password", ("restic_password", "restic_password_file")),
+        ("3", "Database data root", ("data_root",)),
+        ("4", "ACME email", ("acme_email",)),
+        ("5", "DNS provider and credentials", ("dns_provider", "dns", "dns_file")),
+        ("6", "Backup repository", ("repository", "rclone_config")),
+        ("7", "Restic password", ("restic_password", "restic_password_file")),
     )
     selected = ui.choose(
         input_fn,

src/evdb/config.py

@@ -226,6 +226,7 @@ def as_dict(config: Config) -> dict[str, Any]:
         "host": {
             "id": host.id,
             "domain": host.domain,
+            "data_root": str(host.data_root),
             "backup": backup,
             "routing": {
                 "acme_email": host.routing.acme_email,
@@ -395,6 +396,10 @@ def require_valid(config: Config) -> None:
             validator(value)
         except ConfigError as exc:
             errors.append(str(exc))
+    try:
+        validate_data_root(host.data_root, config.paths, host.backup.repository)
+    except ConfigError as exc:
+        errors.append(str(exc))
     for managed in (config.paths.config, config.paths.state):
         unsafe = _unsafe_directory(managed)
         if unsafe is not None:
@@ -514,12 +519,58 @@ def validate_email(value: str) -> str:
     return value
 
 
+def validate_data_root(
+    value: str | Path,
+    paths: Paths | None = None,
+    repository: str | None = None,
+) -> Path:
+    path = Path(value)
+    try:
+        resolved = path.resolve(strict=False)
+    except (OSError, RuntimeError) as exc:
+        raise ConfigError("host.data_root must be a normalized absolute path") from exc
+    if not path.is_absolute() or path != resolved:
+        raise ConfigError("host.data_root must be a normalized absolute path")
+    unsafe = _unsafe_directory(path)
+    if unsafe is not None:
+        raise ConfigError(f"host.data_root is symlinked or unsafe: {unsafe}")
+
+    managed = paths or Paths()
+    reserved = (
+        managed.config,
+        managed.projects,
+        managed.traefik,
+        managed.backups,
+        managed.locks,
+    )
+    if any(_paths_overlap(path, item) for item in reserved):
+        raise ConfigError("host.data_root overlaps an evdb managed path")
+    if (
+        repository is not None
+        and repository_parts(repository) is None
+        and _paths_overlap(path, Path(repository))
+    ):
+        raise ConfigError("host.data_root overlaps the local backup repository")
+    if path != managed.databases:
+        try:
+            parent = path.parent.lstat()
+        except OSError as exc:
+            raise ConfigError(f"host.data_root parent is missing or unsafe: {path.parent}") from exc
+        if stat.S_ISLNK(parent.st_mode) or not stat.S_ISDIR(parent.st_mode):
+            raise ConfigError(f"host.data_root parent is missing or unsafe: {path.parent}")
+        if managed.config == CONFIG_DIR and (parent.st_uid != 0 or parent.st_mode & 0o022):
+            raise ConfigError(f"host.data_root parent must be safely root-owned: {path.parent}")
+        if managed.config == CONFIG_DIR and path.exists() and path.lstat().st_uid != 0:
+            raise ConfigError(f"host.data_root must be root-owned: {path}")
+    return path
+
+
 def _config(data: dict[str, Any], secrets: Secrets, paths: Paths) -> Config:
     if {"databases", "instances", "releases"} & set(data):
         raise ConfigError("unsupported source schema")
     _only(data, {"host", "projects"}, "config")
     host_data = _object(_required(data, "host", "config"), "host")
-    _only(host_data, {"id", "domain", "backup", "routing"}, "host")
+    _only(host_data, {"id", "domain", "data_root", "backup", "routing"}, "host")
     backup_data = _object(_required(host_data, "backup", "host"), "host.backup")
     _only(
         backup_data,
@@ -534,6 +585,7 @@ def _config(data: dict[str, Any], secrets: Secrets, paths: Paths) -> Config:
     host = Host(
         _string(host_data, "id", "host"),
         _string(host_data, "domain", "host"),
+        Path(_string(host_data, "data_root", "host")),
         BackupSettings(
             _string(backup_data, "repository", "host.backup"),
             Path(rclone_value) if rclone_value is not None else None,
@@ -864,6 +916,19 @@ def _unsafe_directory(path: Path) -> Path | None:
     return None
 
 
+def _paths_overlap(left: Path, right: Path) -> bool:
+    try:
+        left.relative_to(right)
+        return True
+    except ValueError:
+        pass
+    try:
+        right.relative_to(left)
+        return True
+    except ValueError:
+        return False
+
+
 def _json_credentials(value: str) -> list[str]:
     try:
         data = json.loads(value)