kitsune-kit 0.4.0 → 0.5.0

data/docs/getting-started.md

@@ -0,0 +1,133 @@
+# Getting started
+
+This guide creates a new DigitalOcean server from an empty project. Read the plan before applying it; a real run creates billable infrastructure.
+
+## 1. Prepare DigitalOcean
+
+Create a DigitalOcean API token with the minimum access needed to inspect/create/delete Droplets and, only if configured, domain records. Keep development/CI infrastructure in a separate project or account where practical.
+
+Upload your public SSH key to DigitalOcean and note its numeric key ID. Kitsune Kit needs the provider key ID at creation time and the corresponding private key locally.
+
+```bash
+chmod 600 ~/.ssh/id_ed25519
+export DO_API_TOKEN="your-token"
+```
+
+Do not put the token or a private key in `.kitsune/config.yml`.
+
+## 2. Initialize the project
+
+```bash
+mkdir myapp-infrastructure
+cd myapp-infrastructure
+kit init
+```
+
+Generated files:
+
+```text
+.kitsune/config.yml
+.kitsune/environments/development.yml
+.kitsune/environment
+```
+
+Kitsune Kit adds state, logs, support bundles, known hosts and the selected environment to `.gitignore`. Commit the non-secret configuration files; back up `.kitsune/state/` securely outside Git once resources exist.
+
+`kit init` does not overwrite generated files. `kit init --force` replaces them and should only be used intentionally.
+
+## 3. Edit configuration
+
+At minimum, replace:
+
+```yaml
+server:
+  name: myapp-development
+  region: sfo3
+  size: s-1vcpu-1gb
+  image: ubuntu-24-04-x64
+  ssh_key_id: "12345678"
+
+ssh:
+  key_path: ~/.ssh/id_ed25519
+```
+
+Keep `services.postgres.publish` and `services.redis.publish` false unless remote TCP access is a deliberate requirement. See [Configuration](configuration.md).
+
+## 4. Run preflight checks
+
+```bash
+kit doctor
+```
+
+Before the Droplet exists, `doctor` reports it as a warning. Configuration, local key permissions, provider credentials and state should pass. `doctor` never creates or modifies resources.
+
+## 5. Review the plan
+
+```bash
+kit plan
+```
+
+Markers are:
+
+```text
++ create
+~ update
+- delete
+= no change
+```
+
+A planned immutable server change is destructive and `apply` refuses to replace it implicitly. Destroying a server is always a separate, explicitly confirmed action.
+
+## 6. Apply
+
+```bash
+kit apply
+```
+
+Kitsune Kit creates and records the provider ID before waiting, so a timeout can be resumed without creating a duplicate. Remote operations then configure the user, SSH, firewall, updates, swap, Docker, optional services and DNS.
+
+On the first SSH connection, Kitsune Kit displays the key type and SHA256 host-key fingerprint. Verify it through an independent trusted channel before accepting it. The accepted key is stored in `.kitsune/known_hosts` with restricted permissions.
+
+If a step fails:
+
+```bash
+kit status
+kit resume
+```
+
+Only unfinished steps from a compatible saved run are executed. Do not delete state to work around a failure.
+
+## 7. Verify and reapply
+
+```bash
+kit doctor
+kit plan
+kit apply
+```
+
+After a successful run, `doctor` should pass and `plan` should contain zero changes. Repeated `apply` is expected to be idempotent.
+
+## Non-interactive first run
+
+CI cannot answer confirmation or host-key prompts. First obtain and independently verify the expected fingerprint. Then run:
+
+```bash
+kit plan --format json --no-input
+kit apply \
+  --format json \
+  --no-input \
+  --yes \
+  --trust-host-key SHA256:verified-fingerprint
+```
+
+The fingerprint option must match exactly. It is not a switch that disables host-key verification.
+
+## Production checklist
+
+- Use a dedicated environment overlay and `kit env use production`.
+- Restrict `ssh.allowed_cidrs` to operator/CI networks when practical.
+- Keep data services private or specify the smallest possible allowed CIDRs.
+- Use generated, unique PostgreSQL and Redis passwords.
+- Run `doctor`, archive the reviewed JSON plan and back up local state.
+- Test service backup and restore procedures before relying on them.
+- Retain provider-console access while changing SSH policy.

data/docs/providers/digitalocean.md

@@ -0,0 +1,52 @@
+# DigitalOcean provider
+
+DigitalOcean is the only provider supported in the 0.5 release. Provider calls are isolated behind the provider contract so the core and presentation layers do not depend on DropletKit directly.
+
+## Credentials and permissions
+
+Set `provider.token_env` to the name of a process environment variable (default `DO_API_TOKEN`) and export the token before running Kitsune Kit.
+
+The token needs Droplet read/write access. DNS read/write access is required only when `dns.domains` is non-empty. Prefer a dedicated account/project for CI and test resources, and grant the minimum scopes available for your workflow.
+
+## SSH key IDs
+
+`server.ssh_key_id` is the DigitalOcean key ID, not a filesystem path or public-key text. `ssh.key_path` is the corresponding local private key. Kitsune Kit passes the ID only during Droplet creation and never displays it in plan details.
+
+For the exact commands to create a dedicated test key, upload its public half, retrieve the numeric ID and
+configure local or GitHub E2E runs, see [DigitalOcean E2E](../testing.md#digitalocean-e2e).
+
+## Identity and ownership
+
+A server match requires both the exact configured name and all configured tags. Keep the default `kitsune-managed` tag. State stores the returned provider ID immediately after creation.
+
+Deletion requires:
+
+1. an ID present in local managed state;
+2. the provider object still existing or being confirmed absent;
+3. exact configured name and expected tags when it exists;
+4. exact operator confirmation.
+
+Kitsune Kit never deletes a Droplet by name alone and never adopts a same-name untagged Droplet.
+
+## Creation and timeouts
+
+Before server lookup or creation, Kitsune Kit queries DigitalOcean's region, size and distribution-image catalogs. The selected region must be active, the size must be available there, and the image must support it. An unavailable choice is an actionable configuration error; no Droplet is created.
+
+The creation request includes name, region, size, supported Ubuntu image, SSH key ID and tags. Kitsune Kit polls until the Droplet is active and has a public IPv4 address. A timeout is retryable: the saved provider ID lets `kit resume` wait for the same Droplet instead of creating another.
+
+Provider authentication, quota, validation and connectivity errors are mapped to stable domain error codes. Technical provider messages are not treated as safe user output.
+
+## DNS
+
+For each hostname, Public Suffix List rules determine the zone and relative record name. Kitsune Kit finds records by exact zone/name/type, persists returned record IDs and captures previous values before an update.
+
+Rollback deletes records it created and restores records it updated. If a run fails between records, each completed record is already in state and resume does not duplicate it.
+
+The zone must already exist in the DigitalOcean account; Kitsune Kit does not transfer domains or change nameservers.
+
+## Real-infrastructure tests
+
+The manually dispatched E2E suite uses unique names, tags every Droplet with `kitsune-ci` and
+`kitsune-expires-EPOCH`, saves state immediately and destroys in `ensure`. A separate always-run cleanup job
+deletes only expired resources carrying both conventions after an authorized workflow run. See
+[Testing](../testing.md).

data/docs/releasing.md

@@ -0,0 +1,43 @@
+# Release process
+
+Kitsune Kit follows Semantic Versioning. Before 1.0, minor releases may make incompatible changes, but every schema or command change must be documented in `CHANGELOG.md`.
+
+## One-time repository setup
+
+1. Protect `main` and version tags; require the CI jobs.
+2. Create a GitHub environment named `release` with required reviewers.
+3. Configure `release.yml` as a trusted publisher for `kitsune-kit` on RubyGems.org, scoped to the `release` environment.
+4. Require MFA for gem owners and protect GitHub accounts with strong MFA.
+5. Configure the separate DigitalOcean E2E secrets/account and budget alerts.
+
+The workflow uses OIDC short-lived credentials through `rubygems/release-gem`; no `GEM_HOST_API_KEY` secret is stored.
+
+## Release checklist
+
+1. Ensure normal CI is green on every supported Ruby and Ubuntu combination.
+2. Run/inspect the latest real DigitalOcean lifecycle; stable releases must not proceed without a green E2E.
+3. Run locally:
+
+   ```bash
+   bundle exec rake ci
+   bundle exec rake integration
+   ```
+
+4. Move `Unreleased` entries into a dated version section and restore an empty `Unreleased` section.
+5. Update `lib/kitsune/kit/version.rb` once. The version must match the intended `vVERSION` tag.
+6. Build and inspect:
+
+   ```bash
+   bundle exec rake build
+   gem specification pkg/kitsune-kit-VERSION.gem
+   gem contents --show-install-dir kitsune-kit # after isolated install
+   ```
+
+7. Install the artifact in a clean gem directory and run `kit version`, `kit help`, and a temporary `kit init`.
+8. Commit the version/changelog, obtain review, merge and create a signed or protected `vVERSION` tag.
+9. Push only the tag. Approve the protected `release` environment after rechecking the commit/tag/version.
+10. Confirm RubyGems version/checksum, generated GitHub Release and installation from RubyGems.
+
+## Recovery
+
+Do not overwrite/reuse a published version. If publishing succeeds but GitHub Release creation fails, create the release for the same immutable tag/artifact. If a package is defective, publish a new patch version and document the problem. Follow RubyGems owner/yank guidance only for a genuine security or legal incident.

data/docs/roadmap.md

@@ -0,0 +1,46 @@
+# Roadmap and extension decisions
+
+Kitsune Kit remains deliberately narrow until the complete DigitalOcean lifecycle is repeatedly green. This file
+records decisions for the priority-4 items in the professionalization plan so “deferred” does not mean
+“forgotten.”
+
+## Hetzner evaluation
+
+The current provider boundary is sufficiently generic for a second server adapter: credential validation,
+server-spec validation, exact lookup/ID lifecycle, readiness and normalized `ServerRecord`. A Hetzner adapter
+would need to map its locations, server types, images, SSH keys, status/IP representation, errors and deadlines
+to that contract and pass the same fake/real lifecycle tests.
+
+DNS must not be silently assumed equivalent to server provisioning. A future adapter must either implement the
+existing exact-ID DNS contract through the selected Hetzner DNS product or declare DNS unsupported before
+planning; provider conditionals must not leak into CLI/TUI code.
+
+Decision: do not add Hetzner before the DigitalOcean E2E is reliably green and the adapter API has survived a
+released 0.5.x version. When that gate is met, begin with a contract-only spike and an opt-in create/wait/resume/delete
+test in an isolated account. This is an evaluated sequencing decision, not a claim of current support.
+
+## External services
+
+Implemented in schema version 1 through `services.TYPE.mode: external`. External endpoints are validated and
+visible through `status`, but they produce no VPS operation. Kitsune Kit refuses install, backup, remove and
+destroy-data because ownership remains with the service provider. This avoids assuming every database is a
+local Compose service without pretending to provision arbitrary vendors.
+
+Provider-specific database creation, TLS certificate distribution, database/user setup and backup APIs remain
+out of scope until a concrete integration is selected and can have ownership/rollback semantics.
+
+## Hooks and plugins
+
+Decision: no arbitrary pre/post shell hooks or dynamic plugin loading before real use cases exist. Such a system
+would enlarge the command-injection, secret and rollback surface while weakening plan accuracy. Small,
+versioned ports remain the extension mechanism. A future hook proposal must define:
+
+- a concrete use case that cannot be represented as an operation;
+- typed inputs/outputs and secret annotations;
+- whether it is observable during plan;
+- timeout, idempotence, retry and cancellation behavior;
+- ownership and rollback semantics;
+- human/JSON/TUI event behavior;
+- hostile-input, contract and E2E tests.
+
+Until those requirements are met, no hook API is promised.

data/docs/security-audit.md

@@ -0,0 +1,130 @@
+# Manual security audit
+
+- Review date: 2026-08-14
+- Scope: the `0.5.0` direct rewrite in this repository
+- Method: manual source review plus static, unit, contract, integration and real DigitalOcean E2E gates
+- Result: no unresolved critical, high or medium findings were identified in the reviewed scope
+
+This is a maintainer security review, not a third-party penetration test or certification. Version 0.5.0 remains
+pre-1.0 while hosted CI and timed usability acceptance complement the green real-infrastructure result.
+
+## Threat model and boundaries reviewed
+
+The review assumes the local operator account, project configuration, selected first-use SSH fingerprint and
+provider account are trusted. It treats configuration values, remote output, provider responses, existing
+same-name resources, terminal state and interruption timing as potentially hostile or inconsistent.
+
+The following boundaries were inspected:
+
+- YAML loading, schema/type validation, path normalization and environment precedence;
+- secret acquisition, redaction, remote `.env` generation, logs, state and support bundles;
+- provider authentication/error translation, exact IDs/tags and destructive ownership checks;
+- SSH host-key handling, command argument escaping, uploads, deadlines and preserved-session recovery;
+- user/sudoers, SSH policy, UFW, swap, unattended upgrades, Docker and metrics scripts;
+- Compose generation, database exposure, `DOCKER-USER` ownership and data lifecycle;
+- DNS zone parsing, exact record IDs, partial persistence and rollback;
+- atomic state, locks, resumable journals, cancellation and terminal restoration;
+- E2E credentials, TTL tags, cleanup filtering and release supply-chain configuration.
+
+## Security properties verified in code and tests
+
+### Input and command execution
+
+Configuration uses safe YAML parsing and a closed nested schema. Resource names, environment names, users,
+ports, CIDRs, domains, images, paths and secret-variable names are validated before external adapters are
+constructed. The SSH adapter sends an executable and separately Shellwords-escaped arguments; uploads send
+base64 over stdin. Hostile tests cover shell metacharacters, command substitution, traversal and embedded
+control characters.
+
+### Secrets
+
+Configuration/state store secret-variable names or hashes, never service passwords or provider tokens.
+Human, JSON, TUI, file-log, error and support-bundle paths share the central filter. It redacts registered
+values, sensitive hash keys, URL credentials and complete private-key blocks. Service `.env` files are mode
+`0600`. Redis uses a literal runtime environment reference in its command and `REDISCLI_AUTH` healthcheck so
+Compose does not resolve the password into container command arguments.
+
+### SSH and firewall recovery
+
+First-use SSH trust requires the exact displayed SHA256 fingerprint; subsequent access uses the isolated
+known-hosts file. User creation validates sudoers with `visudo`. SSH policy validates with `sshd -t`, initially
+keeps key-based root recovery, verifies a fresh deploy connection, disables root and verifies again. The
+authenticated transition session remains open so a failed fresh verification can restore policy before the
+session closes.
+
+UFW adds the desired SSH route before removing stale rules marked by Kitsune Kit. Apply/finalize is verified with a
+fresh connection. Rollback preserves pre-existing activation/package state and removes only recorded owned
+rules. Docker-published database ports have separately owned `DOCKER-USER` allow/drop transactions.
+
+### Ownership and destruction
+
+Server deletion requires a recorded provider ID, exact-name confirmation and matching provider identity/tags.
+Provider deletion happens before DNS cleanup, so a rejected provider deletion leaves DNS unchanged; cleanup is
+retryable if DNS fails afterward. DNS updates store every exact ID and prior value immediately.
+
+Service `remove` preserves volumes. `destroy-data` requires `TYPE@ENV`; `--yes` is insufficient. Interactive
+use offers a data archive, and automation can request one with `--backup-before-destroy`. Destruction refuses
+to proceed when managed state is absent.
+
+### Files, state and supply chain
+
+State, known-hosts, logs and support artifacts use restricted directories/files. State writes lock, validate,
+back up, fsync and atomically rename. Unsupported schemas fail instead of being guessed. Logs retain at most 20
+files. Temporary installer/key/config files are removed on failures; metrics downloads require an operator-set
+SHA256. The internal backup container image is digest-pinned.
+
+Bundler Audit was run with ruby-advisory-db commit
+`0c1a72a61f08ac6758c5124c083bf01db4638456` and reported no known vulnerabilities. CI also runs RuboCop,
+ShellCheck, branch-coverage gates, adapter contracts, gem build/install smoke tests and the supported Ruby/Ubuntu
+matrices.
+
+The local normal suite passed 243 examples with 87.05% line, 66.34% overall branch and 88.99% domain-core
+branch coverage. The Docker-backed SSH/Bash/TUI integration passed 8 examples on Ubuntu 22.04 and the same 8
+examples on Ubuntu 24.04. Pseudo-terminal cases verify restoration on normal exit and `SIGINT`. These local
+results are complemented by the real-provider evidence below.
+
+The baseline suite and core coverage gate passed under the supported Ruby 3.2.2, 3.3 and 3.4 runtimes. Six
+additional bounded SSH-bootstrap retry, server-state drift and real SDK-interface examples passed under the
+local Ruby 3.2.2 gate.
+Standard-library extractions needed by Kitsune Kit and the current DigitalOcean SDK are explicit runtime dependencies,
+so warnings cannot corrupt structured output on newer Ruby releases.
+
+## Findings corrected during this review
+
+1. The real E2E CLI checks did not explicitly select the provisioned `e2e` environment. They now do and assert
+   that rollback leaves only the server state.
+2. Redis authentication was represented in a Compose command form that could resolve the secret into command
+   arguments. It now uses a literal runtime environment reference and `REDISCLI_AUTH`.
+3. Service data destruction lacked an interactive backup offer and exact-name prompt. Both are now present,
+   with an explicit automation flag and tests.
+4. Docker repository key/config and sudoers/SSH-policy temporary files could remain partial after interruption.
+   They now use guarded temporary files followed by restrictive installation and cleanup traps.
+5. The TTL cleanup script had no isolated proof around its destructive filter. It is now dependency-injectable,
+   dry-run by default and tested to delete only expired `kitsune-ci` IDs.
+
+## Residual risks and required operational validation
+
+- The real DigitalOcean E2E passed locally on 2026-08-14 in 7 minutes 12 seconds (seed 12020; 1 example, 0
+  failures). It exercised provider behavior, Ubuntu 24.04, systemd, UFW, Docker networking, SSH hardening,
+  PostgreSQL/Redis isolation, zero-change reapply, rollback and exact Droplet cleanup. The operator confirmed the
+  Droplet was removed.
+- The same credentialed workflow has not yet been observed on a GitHub-hosted runner, so runner permissions,
+  secret wiring and cleanup-job orchestration remain release gates.
+- Ruby 4 is outside the 0.5.0 support contract because the current DigitalOcean SDK constrains
+  `faraday-retry` to a release series that requires Ruby `< 4`; CI and gem metadata enforce this boundary.
+- User-selected PostgreSQL/Redis image tags are mutable unless pinned by digest. Production configurations
+  should pin and deliberately update reviewed multi-platform digests.
+- Data archives are created on the same Droplet. They are not disaster recovery until copied to independent,
+  access-controlled storage and restoration is tested.
+- Local state is not encrypted or centrally shared. It contains no intended secrets, but its integrity and
+  availability establish ownership; secure backups are required for team operation.
+- Provider token least privilege and budget controls depend on DigitalOcean account capabilities and operator
+  configuration. Use a separate CI project/account, alerts and short-lived or narrowly scoped credentials where
+  available.
+- Docker-group and passwordless-sudo membership make the deploy key root-equivalent by design.
+
+## Release decision
+
+The reviewed implementation passed its real-provider lifecycle, including confirmed cleanup and closed ports
+5432/6379. The review supports the 0.5.0 release; hosted CI and timed new-user acceptance remain follow-up
+evidence before 1.0 rather than unresolved security findings.

data/docs/security.md

@@ -0,0 +1,116 @@
+# Security model
+
+Kitsune Kit changes remote security policy and can destroy infrastructure. Its design favors explicit ownership, verified transitions and refusal over implicit adoption.
+
+## Trust boundaries
+
+Kitsune Kit trusts:
+
+- the local machine/user running the gem;
+- configuration committed by the project;
+- secrets supplied through the process environment;
+- the independently verified first SSH host-key fingerprint;
+- provider and package repositories over TLS;
+- local state as the record of which resources Kitsune Kit owns.
+
+Compromise of the local account, repository, environment, private key or state can invalidate these assumptions. Kitsune Kit is not a secrets vault and does not encrypt local files.
+
+## Secrets
+
+Never place API tokens or service passwords in YAML, command arguments, state or Git. Configuration stores only environment-variable names. Secret values are registered with a central redactor before event reporting/logging.
+
+```bash
+export DO_API_TOKEN="..."
+export POSTGRES_PASSWORD="..."
+export REDIS_PASSWORD="..."
+```
+
+Generated service `.env` files exist only on the remote server with mode `0600`. Compose output, fingerprints and local state do not contain plaintext passwords. Newlines, carriage returns and NUL bytes are rejected.
+
+Process environments may be observable by privileged local processes and CI administrators. Use the secret store of your CI platform, limit token scope, rotate credentials and avoid shell tracing.
+
+## SSH
+
+Kitsune Kit never uses `verify_host_key: :never` in production adapters. A new key raises a prompt containing the exact SHA256 fingerprint. Acceptance records it in `.kitsune/known_hosts`; later sessions use strict matching.
+
+`--trust-host-key` accepts only an exact fingerprint and is intended for independently verified non-interactive bootstrap. A mismatch fails. Key changes are not automatically accepted.
+
+SSH hardening preserves a recovery route:
+
+1. bootstrap using deploy or root access;
+2. create/configure the deploy user;
+3. verify a second deploy-user connection;
+4. validate generated `sshd_config` with `sshd -t`;
+5. reload first with key-based root recovery still enabled;
+6. verify a new deploy-user connection, then disable root and verify again;
+7. add the new firewall route before removing a stale route owned by Kitsune Kit and verify deploy access once more.
+
+The transport keeps the already authenticated session open across each safety-critical transition. Fresh verification uses a separate connection; if it fails before or after finalization, the preserved session runs the script rollback before it closes. A recovery failure is surfaced as a verification error with provider-console guidance. Kitsune Kit does not modify unrelated SSH/firewall configuration during rollback.
+
+## Command and file safety
+
+Remote commands are a validated executable plus separately Shellwords-escaped arguments. File uploads are base64 data over stdin, not interpolated shell source. Absolute remote paths and modes are validated before connecting.
+
+Generated Compose documents are built as Ruby hashes and serialized with YAML. Resource names, users, ports, CIDRs, images, domains and environment names have allow-list validation. Tests include metacharacters, substitutions, traversal and embedded newline attacks.
+
+Versioned shell scripts use `set -Eeuo pipefail`, explicit action dispatch and verification. ShellCheck runs in CI.
+
+## Firewall and data services
+
+PostgreSQL and Redis do not publish host ports by default. When publishing is enabled:
+
+- at least one valid allowed CIDR is required;
+- Compose binds only the configured IPv4 address/port;
+- matching allow and terminal drop rules are installed in Docker's `DOCKER-USER` chain because Docker-published ports can bypass UFW forwarding policy;
+- only rules recorded as created by Kitsune Kit are reconciled or removed.
+
+Use private networking or an application-local Docker network whenever possible. Never publish a database to `0.0.0.0` with a broad CIDR unless the exposure is deliberate and independently audited.
+
+## Ownership and destructive actions
+
+Kitsune Kit records provider IDs, DNS record IDs, remote fingerprints, file backups and firewall ownership. Same-name resources without the expected tags/state are not adopted or deleted.
+
+Semantics:
+
+| Operation | Server | Containers | Data volume | Configuration |
+| --- | --- | --- | --- | --- |
+| `rollback` | Keep | Restore/remove managed | Keep | Restore captured state |
+| service `remove` | Keep | Remove | Keep | Keep ownership record |
+| service `destroy-data` | Keep | Remove | Delete | Delete managed service files/state |
+| server `destroy` | Delete | Delete with server | Delete with server | Restore/remove managed DNS after provider deletion |
+
+`--yes` never authorizes permanent service data or server destruction. Exact confirmation strings are required.
+Interactive service-data destruction offers a restricted archive first. In automation,
+`--backup-before-destroy` requests it explicitly; copy that same-server archive to independent storage.
+
+The deploy user belongs to the `docker` group and has passwordless sudo, so it is effectively a privileged
+administrator. Protect its private key as a root credential, restrict SSH CIDRs where possible and rotate the
+key after suspected exposure.
+
+## State, logs and diagnostics
+
+State/log/support directories and files use restrictive permissions. State writes use file locks, fsync, atomic rename and backups. Logs are structured, redacted and rotated. Support bundles are local JSON and never transmitted.
+
+Back up `.kitsune/state/` securely. If state is lost, recover it rather than recreating ownership from names. Inspect support bundles before sharing; redaction is defense in depth, not proof that arbitrary user-provided text contains no sensitive information.
+
+When both state copies are lost, `kit server import` is the limited recovery path. It requires an exact numeric provider ID and exact-name confirmation, verifies the complete configured server identity, and imports only server metadata. It deliberately does not claim remote resources or DNS records.
+
+## Supply chain
+
+- Docker is installed from Docker's official signed apt repository.
+- Metrics installation is off by default. Enabling it requires an explicitly configured SHA256 for the downloaded script; no `curl | sh` pipeline is used.
+- Ruby dependencies are locked for development, audited with Bundler Audit and updated through Dependabot.
+- Release metadata requires MFA on RubyGems. Releases should use trusted publishing and protected tags when configured.
+
+Container service tags are mutable unless pinned by digest. For production reproducibility, use an image reference ending in `@sha256:...`, test it in staging and update deliberately.
+
+The internal Alpine image used only to archive service volumes is multi-platform and pinned to the published Docker Official Image manifest digest. Its source is the [Docker Hub `alpine:3.20` manifest](https://hub.docker.com/layers/library/alpine/3.20/images/sha256-ac77ebc035f69184acb2660028580c9053f6d0f892de7933e1456d8b5e0ac085). Updating it requires reviewing the new manifest and running backup/restore tests.
+
+Kitsune Kit contains no telemetry or automatic upload path. Logs and support bundles remain local unless the
+operator deliberately shares them.
+
+The latest manual review and its limitations are recorded in [Security audit](security-audit.md).
+
+## Reporting vulnerabilities
+
+Follow [SECURITY.md](../SECURITY.md). Do not include real credentials, addresses or domains in a public issue or reproduction.

data/docs/services/postgres.md

@@ -0,0 +1,78 @@
+# PostgreSQL service
+
+PostgreSQL is an optional Docker Compose service managed by Kitsune Kit on the target server. It is disabled and private by default.
+
+## Enable
+
+```yaml
+services:
+  postgres:
+    enabled: true
+    image: postgres:17
+    publish: false
+    bind: 127.0.0.1
+    allowed_cidrs: []
+    port: 5432
+    password_env: POSTGRES_PASSWORD
+```
+
+```bash
+export POSTGRES_PASSWORD="$(ruby -rsecurerandom -e 'print SecureRandom.base64(36)')"
+kit plan
+kit service postgres install
+```
+
+The Compose project is `kitsune-ENV-postgres`, attached to the external `kitsune-private` network. Data is stored in its named `data` volume. The database name is `app_ENV` with `-` converted to `_`; the user is `postgres`.
+
+## Connectivity
+
+With `publish: false`, there is no host port mapping. Applications on `kitsune-private` can connect using Docker service/network addressing and the configured credentials.
+
+Publishing is an explicit exception:
+
+```yaml
+publish: true
+bind: 0.0.0.0
+allowed_cidrs:
+  - 203.0.113.10/32
+```
+
+Kitsune Kit requires at least one CIDR and installs owned `DOCKER-USER` allow/drop rules. Validate the result externally; UFW alone does not reliably restrict Docker-published ports.
+
+## Status, backup and removal
+
+```bash
+kit service postgres status
+kit service postgres backup
+kit service postgres remove --yes
+```
+
+Backup pauses the service, archives the named volume into a restricted remote backup directory and unpauses in an `ensure` path. The returned path is on the server. Copy it to independent storage and test restoration; creating an archive on the same Droplet is not disaster recovery.
+
+`remove` runs Compose down without `--volumes`, removes only firewall rules owned by Kitsune Kit and marks the service removed. Data remains.
+
+## Permanent destruction
+
+```bash
+kit service postgres backup
+kit service postgres destroy-data --backup-before-destroy --confirm-destroy postgres@production
+```
+
+In an interactive terminal, `destroy-data` offers to create the archive and then requires typing
+`postgres@ENV`. Automation uses `--backup-before-destroy` when desired and must always provide the exact
+`--confirm-destroy` value. The data archive is retained, while Compose volumes, managed configuration
+backups/files, markers and service state are removed. Copy the archive off the server before relying on it;
+`--yes` cannot replace the exact confirmation.
+
+## Updates and rollback
+
+Changing the image/configuration/secret changes the service fingerprint. Before an update, Kitsune Kit backs up managed Compose/env files. It validates Compose, waits for health, reconciles firewall rules and only then records the new state. Failed updates restore previous files and restart the prior service where possible.
+
+`kit rollback` restores captured managed configuration and preserves the volume. It does not promise database-level downgrade compatibility; test image upgrades and rollback in staging.
+
+## External PostgreSQL
+
+Set `enabled: true`, `mode: external`, `host` and `port` to represent a provider-managed database without
+installing it on the VPS. `kit service postgres status` reports the endpoint; install, backup, remove and
+destroy-data are intentionally unavailable. Kitsune Kit does not test provider TLS, create users/databases or
+manage external backups. Supply those through the database provider and application deployment system.

data/docs/services/redis.md

@@ -0,0 +1,53 @@
+# Redis service
+
+Redis is an optional Docker Compose service managed by Kitsune Kit on the target server. It is disabled, password-protected and private by default.
+
+## Enable
+
+```yaml
+services:
+  redis:
+    enabled: true
+    image: redis:7.2
+    publish: false
+    bind: 127.0.0.1
+    allowed_cidrs: []
+    port: 6379
+    password_env: REDIS_PASSWORD
+```
+
+```bash
+export REDIS_PASSWORD="$(ruby -rsecurerandom -e 'print SecureRandom.base64(36)')"
+kit plan
+kit service redis install
+```
+
+The generated service enables append-only persistence, requires the password and attaches to `kitsune-private`. Data lives in the Compose named `data` volume.
+
+## Connectivity and publishing
+
+With `publish: false`, only containers on the private Docker network can connect. If TCP access from outside the host is unavoidable, set `publish: true`, choose a bind address and provide narrow `allowed_cidrs`. Kitsune Kit installs matching `DOCKER-USER` rules and a final drop rule it owns.
+
+Never treat the Redis password as an adequate substitute for network isolation. Validate port 6379 from an untrusted external network after any firewall/Docker change.
+
+## Lifecycle
+
+```bash
+kit service redis status
+kit service redis backup
+kit service redis remove --yes
+kit service redis destroy-data --backup-before-destroy --confirm-destroy redis@production
+```
+
+- `backup` pauses Redis, archives its volume remotely, then unpauses even if archiving fails.
+- `remove` removes the container and owned firewall rules but preserves the data volume.
+- `destroy-data` removes the volume, service files, backups and state after exact confirmation.
+- `kit rollback` restores captured managed files/settings while preserving data.
+
+Copy backups away from the Droplet, control access to them and regularly test restoration. Image downgrades may not understand data written by a newer Redis version; operational rollback and data-format compatibility are separate concerns.
+
+## External Redis
+
+Set `enabled: true`, `mode: external`, `host` and `port` for a provider-managed endpoint. Status is available,
+but Kitsune Kit refuses install, backup, remove and destroy-data because those belong to the external provider. TLS,
+availability and backup policy remain the operator/provider responsibility.