kamal-backup 0.1.2 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67d289224a384dc9f1546799c15b1bf69649060d49ff8018869b098924104704
-  data.tar.gz: 4307158e1472c2aeafbab424fbb1d2af50a1a1cc6a43b2b11ea6dfae5e3b1d42
+  metadata.gz: c69dd196192b66424004ae3769d75602862227ad958e056288e1cb49b8242a8a
+  data.tar.gz: fa70cfffdf1d95212700244fcdfbb5e7b72b8f4eaf27f2898177c16c305fe9d8
 SHA512:
-  metadata.gz: cba47d9ebf7771e7513e24ca6e7c1d30c5bc3660caeb6ab0f4ed945203baadf370778af5b887a7eb39a82664709f9210179c847c1983d29318befe03abe0e8fa
-  data.tar.gz: ff55565395d49eca645732276db416aa2f240b7511468f7d96296821c776937404862835ba977bd7005efba7ea91fb2269f7e7b0f7f4db7e751cb1b375da9ea2
+  metadata.gz: c1764bd5d9a81b9d705838a27f857a679efebe7b2c3ff64be0f4faffc440678e1958124f0cb8ca81c24fa5e30380324d20d42447ae20e5b33f7d946eab7dcec4
+  data.tar.gz: f929aecfd15c9b2ed34560292217a97e4ceff31fd4fad1b9ce0e2589af862cd725a45a275c3755ddc744bb8f0e8703c187aa96537664431b93cc4a2841ae4627

data/README.md

@@ -1,82 +1,66 @@
-# kamal-backup
+<div align="center">
 
-`kamal-backup` gives Rails apps a clean backup and restore workflow for Kamal.
+<img src="docs/assets/images/logo.svg" alt="kamal-backup" height="96">
 
-It backs up:
+<h1>kamal-backup</h1>
 
-- PostgreSQL, MySQL/MariaDB, or SQLite
-- file-backed Active Storage and other mounted app files
+<strong>The easiest way to run scheduled backups for a Rails app deployed with Kamal.</strong>
 
-It restores in two clear modes:
+[![Gem Version](https://img.shields.io/gem/v/kamal-backup.svg)](https://rubygems.org/gems/kamal-backup)
+[![CI](https://github.com/crmne/kamal-backup/actions/workflows/ci.yml/badge.svg)](https://github.com/crmne/kamal-backup/actions/workflows/ci.yml)
+[![Docker Image](https://img.shields.io/badge/image-ghcr.io%2Fcrmne%2Fkamal--backup-blue)](https://github.com/crmne/kamal-backup/pkgs/container/kamal-backup)
+[![Docs](https://img.shields.io/badge/docs-kamal--backup.dev-blue)](https://kamal-backup.dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-- `restore local`: pull a production backup onto your machine
-- `restore production`: restore back into live production
+</div>
 
-And it drills in two clear modes:
+---
 
-- `drill local`: prove the backup works on your machine
-- `drill production`: restore into scratch targets on production infrastructure, run checks, and record evidence
+Backups for Rails apps deployed with Kamal should not become a separate ops project.
 
-Under the hood it uses [restic](https://restic.net/) for encrypted backup storage and repository management.
+`kamal-backup` is one Kamal accessory that runs encrypted backups for your Rails database and file-backed Active Storage files on a schedule. It also gives you restore drills and redacted evidence for security reviews like CASA.
+
+If you already deploy with Kamal, backups should feel like adding one more accessory.
 
 ## Why Rails teams use it
 
-`kamal-backup` is aimed at the common self-hosted Rails setup where:
+Most self-hosted Rails apps need the same things:
 
-- the app is deployed with Kamal
-- the database is PostgreSQL, MySQL/MariaDB, or SQLite
-- file data lives on a mounted volume
-- you need real restore drills and evidence for CASA or another security review
+- scheduled backups for PostgreSQL, MySQL/MariaDB, or SQLite
+- file-backed Active Storage backups from mounted volumes
+- a fast way to restore production data locally
+- restore drills that do not touch the live production database
+- evidence that says more than "the backup job is green"
 
-If your app already stores Active Storage blobs directly in S3, there may be no local file path for `BACKUP_PATHS` to capture. In that case, `kamal-backup` still covers the database side, but object-storage backups are a separate concern.
+`kamal-backup` packages that workflow into a small Ruby gem, a production accessory image, and a restic repository.
 
-## Quick Start
+## Quick start
 
-Add the gem in your Rails app:
+Add the gem:
 
-```ruby
+```rb
 group :development do
   gem "kamal-backup"
 end
 ```
 
-Install it and generate the shared config stub:
+Generate the config file and accessory snippet:
 
 ```sh
 bundle install
 bundle exec kamal-backup init
 ```
 
-That creates:
-
-- `config/kamal-backup.yml`
-
-For most Rails apps, that is enough. `restore local` and `drill local` can infer:
-
-- the development database target from `config/database.yml`
-- the local files target from `storage`
-- the local drill state directory from `tmp/kamal-backup`
-
-Only create `config/kamal-backup.local.yml` if you need to override those local defaults.
-
-Local restore and drill also require the `restic` binary on your machine. The backup accessory image already includes `restic` for production-side commands.
-
-Then add the backup accessory to `config/deploy.yml`:
+Add the accessory to `config/deploy.yml`:
 
 ```yaml
 accessories:
   backup:
     image: ghcr.io/crmne/kamal-backup:latest
     host: chatwithwork.com
+    files:
+      - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
     env:
-      clear:
-        APP_NAME: chatwithwork
-        DATABASE_ADAPTER: postgres
-        DATABASE_URL: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
-        BACKUP_PATHS: /data/storage
-        RESTIC_REPOSITORY: s3:https://s3.example.com/chatwithwork-backups
-        RESTIC_INIT_IF_MISSING: "true"
-        BACKUP_SCHEDULE_SECONDS: "86400"
       secret:
         - PGPASSWORD
         - RESTIC_PASSWORD
@@ -84,227 +68,60 @@ accessories:
         - AWS_SECRET_ACCESS_KEY
     volumes:
       - "chatwithwork_storage:/data/storage:ro"
+      - "chatwithwork_backup_state:/var/lib/kamal-backup"
 ```
 
-Boot it:
-
-```sh
-bin/kamal accessory boot backup
-bin/kamal accessory logs backup
-```
-
-Run the first backup from your app checkout with the local gem and Kamal-style destination selection:
+Put the backup settings in `config/kamal-backup.yml`:
 
-```sh
-bundle exec kamal-backup -d production backup
-bundle exec kamal-backup -d production list
-bundle exec kamal-backup -d production evidence
+```yaml
+accessory: backup
+app_name: chatwithwork
+database_adapter: postgres
+database_url: postgres://chatwithwork@chatwithwork-db:5432/chatwithwork_production
+backup_paths:
+  - /data/storage
+restic_repository: s3:https://s3.example.com/chatwithwork-backups
+restic_init_if_missing: true
+backup_schedule_seconds: 86400
 ```
 
-If you keep multiple deploy configs, pass `-c` the same way Kamal does:
+Boot it. The container runs `kamal-backup schedule` by default:
 
 ```sh
-bundle exec kamal-backup -c config/deploy.staging.yml -d staging backup
-```
-
-Examples live in:
-
-- [examples/kamal-accessory.yml](examples/kamal-accessory.yml)
-- [examples/kamal-backup.yml.example](examples/kamal-backup.yml.example)
-- [examples/kamal-backup.local.yml.example](examples/kamal-backup.local.yml.example)
-
-## What Restic Does Here
-
-`kamal-backup` uses restic as the backup engine and repository format.
-
-In the normal Kamal setup, you do not install restic on the Rails app host. The backup accessory image already includes it. You only point the accessory at a restic repository, usually:
-
-- S3-compatible object storage
-- a restic REST server
-- a filesystem path for local development
-
-If you choose a `rest:` repository, `kamal-backup` does not install or operate that server for you. It is a separate service.
-
-## Commands
-
-The operator-facing command surface is:
-
-```sh
-kamal-backup init
-kamal-backup backup
-kamal-backup restore local [snapshot-or-latest]
-kamal-backup restore production [snapshot-or-latest]
-kamal-backup drill local [snapshot-or-latest]
-kamal-backup drill production [snapshot-or-latest]
-kamal-backup list
-kamal-backup check
-kamal-backup evidence
-kamal-backup schedule
-kamal-backup version
+bundle exec kamal-backup validate
+bin/kamal accessory boot backup
+bin/kamal accessory logs backup
 ```
 
-Production-side commands shell out through Kamal when you pass `-d` or `-c`. Local commands run on your machine.
-
-Remote-backed commands require the local gem version and the backup accessory version to match. If they drift, `kamal-backup` fails fast and tells you to reboot the accessory so it pulls the current `latest` image. `version` is the diagnostic exception: from an app checkout with `config/deploy.yml`, it shows both versions and the sync status even without `-d`.
-
-Common examples:
+Run the first backup and print evidence:
 
 ```sh
 bundle exec kamal-backup -d production backup
-bundle exec kamal-backup -d production check
+bundle exec kamal-backup -d production list
 bundle exec kamal-backup -d production evidence
-bundle exec kamal-backup -d production restore production latest
-bundle exec kamal-backup -d production drill production latest --database app_restore_20260423 --files /restore/files
-bundle exec kamal-backup -d production version
-bundle exec kamal-backup restore local latest
-bundle exec kamal-backup drill local latest --check "bin/rails runner 'puts User.count'"
-```
-
-Use `kamal-backup help`, `kamal-backup help restore`, or `kamal-backup help drill` for task-specific usage.
-
-## How a Backup Run Works
-
-When `kamal-backup backup` runs, it does five things:
-
-1. Validates the app name, restic repository, database settings, and `BACKUP_PATHS`.
-2. Creates a database backup with the database-native export tool.
-3. Streams that database backup into restic with tags such as `type:database`, `adapter:<adapter>`, and `run:<timestamp>`.
-4. Runs one `restic backup` for all configured `BACKUP_PATHS`, tagged as `type:files` with the same `run:<timestamp>`.
-5. Optionally runs `restic forget --prune` and `restic check`.
-
-That shared `run:<timestamp>` tag lets you match the database backup and file backup from the same run.
-
-## Restore
-
-`restore` means "put data back."
-
-`restore local` runs on your machine. With `-d` or `-c`, it asks Kamal for the backup accessory config and uses that as the source of truth for:
-
-- `APP_NAME`
-- `DATABASE_ADAPTER`
-- `RESTIC_REPOSITORY`
-- `LOCAL_RESTORE_SOURCE_PATHS` from the accessory `BACKUP_PATHS`
-
-For a normal Rails app, the local targets come from Rails conventions:
-
-- the development database in `config/database.yml`
-- `storage` as the local files target
-- `tmp/kamal-backup` as the local drill state directory
-
-You still provide the local secrets yourself in env:
-
-- `RESTIC_PASSWORD`
-- `POSTGRES_PASSWORD` or `MYSQL_PWD` when needed
-- `RESTIC_REPOSITORY` when it is not visible through `kamal config`
-
-And you need `restic` installed locally and available on `PATH`.
-
-Example:
-
-```sh
-bundle exec kamal-backup -d production restore local latest
-```
-
-`restore production` is the emergency path back into the live production database and live production file paths:
-
-```sh
-bundle exec kamal-backup -d production restore production latest
-```
-
-It prompts locally, then shells out through Kamal to the backup accessory.
-
-## Restore Drills
-
-`drill` means "restore, check, and record the result."
-
-`drill local` is often the fastest proof for a small app:
-
-```sh
-bundle exec kamal-backup -d production drill local latest --check "bin/rails runner 'puts User.count'"
-```
-
-Like `restore local`, this runs on your machine and requires a local `restic` install.
-
-`drill production` restores into scratch targets on production infrastructure. It does not touch the live production database:
-
-```sh
-bundle exec kamal-backup -d production drill production latest \
-  --database app_restore_20260423 \
-  --files /restore/files \
-  --check "test -d /restore/files/data/storage"
 ```
 
-Every drill writes `last_restore_drill.json` under `KAMAL_BACKUP_STATE_DIR`, and `kamal-backup evidence` includes that latest result.
-
-## Evidence for CASA and Similar Reviews
-
-`evidence` is the JSON summary you can attach to an ops record or security review.
+## What you get
 
-It includes:
+- **Scheduled backups:** the accessory runs continuously and backs up on `backup_schedule_seconds`.
+- **Database and Active Storage coverage:** database dumps plus file-backed Active Storage files from mounted volumes.
+- **Restic underneath:** encrypted, deduplicated snapshots in S3-compatible storage, a restic REST server, or a filesystem repository.
+- **Local restores:** pull production backups into your local Rails app when you need to inspect real data.
+- **Restore drills:** restore into scratch production-side targets and record the result.
+- **Security review evidence:** `kamal-backup evidence` prints redacted JSON with latest snapshots, checks, drills, retention, and tool versions.
 
-- latest database and file snapshots
-- latest `restic check` result
-- latest restore drill result
-- retention settings
-- tool versions
-
-For many reviews, the useful sequence is:
-
-1. scheduled backups
-2. repository checks
-3. a real restore drill
-4. `kamal-backup evidence`
-
-That reads much better to a reviewer than "the backup job is green."
-
-## Configuration Highlights
-
-Core accessory environment:
-
-```sh
-APP_NAME=chatwithwork
-DATABASE_ADAPTER=postgres
-RESTIC_REPOSITORY=s3:https://s3.example.com/chatwithwork-backups
-RESTIC_PASSWORD=change-me
-BACKUP_PATHS=/data/storage
-```
-
-PostgreSQL:
-
-```sh
-DATABASE_ADAPTER=postgres
-DATABASE_URL=postgres://app@app-db:5432/app_production
-PGPASSWORD=change-me
-```
-
-MySQL/MariaDB:
-
-```sh
-DATABASE_ADAPTER=mysql
-DATABASE_URL=mysql2://app@app-mysql:3306/app_production
-MYSQL_PWD=change-me
-```
-
-SQLite:
-
-```sh
-DATABASE_ADAPTER=sqlite
-SQLITE_DATABASE_PATH=/data/db/production.sqlite3
-```
-
-Optional local config files:
+## Docs
 
-- `config/kamal-backup.yml`
-- `config/kamal-backup.local.yml`
+Read the full documentation at **[kamal-backup.dev](https://kamal-backup.dev)**.
 
-`config/kamal-backup.local.yml` is only for nonstandard local targets. Keep secrets such as `RESTIC_PASSWORD`, cloud credentials, and local DB passwords in environment variables, not in YAML files.
+Start here:
 
-## Docs
+- [Getting Started](https://kamal-backup.dev/getting-started/)
+- [How Backups Work](https://kamal-backup.dev/how-backups-work/)
+- [Configuration](https://kamal-backup.dev/configuration/)
+- [Restore Drills](https://kamal-backup.dev/restore-drills/)
+- [Commands](https://kamal-backup.dev/commands/)
 
-Full docs live in [`docs/`](docs/):
+## License
 
-- [`docs/_guide/getting-started.md`](docs/_guide/getting-started.md)
-- [`docs/_guide/configuration.md`](docs/_guide/configuration.md)
-- [`docs/_guide/restore.md`](docs/_guide/restore.md)
-- [`docs/_guide/restore-drills.md`](docs/_guide/restore-drills.md)
-- [`docs/_reference/commands.md`](docs/_reference/commands.md)
+MIT

data/lib/kamal_backup/app.rb

@@ -47,6 +47,11 @@ module KamalBackup
       true
     end
 
+    def validate(check_files: true)
+      config.validate_backup(check_files: check_files)
+      true
+    end
+
     def restore_to_local_machine(snapshot = "latest")
       validate_local_machine_restore
       require_restic!

data/lib/kamal_backup/cli.rb

@@ -33,8 +33,30 @@ module KamalBackup
 
       def local_command_config
         @local_command_config ||= begin
-          defaults = deployment_mode? ? bridge.local_restore_defaults(accessory_name: accessory_name) : {}
-          Config.new(env: command_env, defaults: defaults)
+          if deployment_mode?
+            Config.new(
+              env: command_env,
+              defaults: production_source_defaults,
+              config_paths: [Config::LOCAL_CONFIG_PATH]
+            )
+          else
+            Config.new(env: command_env)
+          end
+        end
+      end
+
+      def production_source_defaults
+        shared_config_source_defaults.merge(bridge.local_restore_defaults(accessory_name: accessory_name))
+      end
+
+      def shared_config_source_defaults
+        config = Config.new(env: {}, config_paths: [Config::SHARED_CONFIG_PATH], load_project_defaults: false)
+
+        {}.tap do |defaults|
+          defaults["APP_NAME"] = config.app_name if config.app_name
+          defaults["DATABASE_ADAPTER"] = config.database_adapter if config.database_adapter
+          defaults["RESTIC_REPOSITORY"] = config.restic_repository if config.restic_repository
+          defaults["LOCAL_RESTORE_SOURCE_PATHS"] = config.backup_paths.join("\n") if config.backup_paths.any?
         end
       end
 
@@ -58,6 +80,10 @@ module KamalBackup
         deployment_mode? || default_deploy_config?
       end
 
+      def validate_deploy_mode?
+        deployment_mode? || default_deploy_config?
+      end
+
       def accessory_name
         @accessory_name ||= bridge.accessory_name(preferred: local_preferences.accessory_name)
       end
@@ -103,6 +129,15 @@ module KamalBackup
         puts("fix: #{accessory_reboot_command}") if status == "out of sync"
       end
 
+      def validate_deploy_config
+        config = Config.new(
+          env: bridge.accessory_environment(accessory_name: accessory_name),
+          config_paths: [Config::SHARED_CONFIG_PATH],
+          load_project_defaults: false
+        )
+        config.validate_backup(check_files: false)
+      end
+
       def confirm!(message)
         return if options[:yes]
 
@@ -149,9 +184,15 @@ module KamalBackup
 
       def shared_config_template
         <<~YAML
-          # Shared defaults for kamal-backup in this app.
-          # Set this when your accessory is not named "backup".
           accessory: backup
+          app_name: your-app
+          database_adapter: postgres
+          database_url: postgres://your-app@your-db:5432/your_app_production
+          backup_paths:
+            - /data/storage
+          restic_repository: s3:https://s3.example.com/your-app-backups
+          restic_init_if_missing: true
+          backup_schedule_seconds: 86400
         YAML
       end
 
@@ -161,15 +202,9 @@ module KamalBackup
             backup:
               image: ghcr.io/crmne/kamal-backup:#{VERSION}
               host: your-server.example.com
+              files:
+                - config/kamal-backup.yml:/app/config/kamal-backup.yml:ro
               env:
-                clear:
-                  APP_NAME: your-app
-                  DATABASE_ADAPTER: postgres
-                  DATABASE_URL: postgres://your-app@your-db:5432/your_app_production
-                  BACKUP_PATHS: /data/storage
-                  RESTIC_REPOSITORY: s3:https://s3.example.com/your-app-backups
-                  RESTIC_INIT_IF_MISSING: "true"
-                  BACKUP_SCHEDULE_SECONDS: "86400"
                 secret:
                   - PGPASSWORD
                   - RESTIC_PASSWORD
@@ -177,6 +212,7 @@ module KamalBackup
                   - AWS_SECRET_ACCESS_KEY
               volumes:
                 - "your_app_storage:/data/storage:ro"
+                - "your_app_backup_state:/var/lib/kamal-backup"
         YAML
       end
     end
@@ -195,15 +231,15 @@ module KamalBackup
         CLI.basename
       end
 
-      desc "local [SNAPSHOT]", "Restore the backup into the local database and local files"
+      desc "local [SNAPSHOT]", "Restore the backup into the local database and Active Storage path"
       def local(snapshot = "latest")
-        confirm!("Restore #{snapshot} into the local database and local files? This will overwrite local data.")
+        confirm!("Restore #{snapshot} into the local database and Active Storage path? This will overwrite local data.")
         puts(JSON.pretty_generate(local_app.restore_to_local_machine(snapshot)))
       end
 
-      desc "production [SNAPSHOT]", "Restore the backup into the production database and production files"
+      desc "production [SNAPSHOT]", "Restore the backup into the production database and Active Storage path"
       def production(snapshot = "latest")
-        confirm!("Restore #{snapshot} into the production database and production files? This will overwrite production data.")
+        confirm!("Restore #{snapshot} into the production database and Active Storage path? This will overwrite production data.")
 
         if deployment_mode?
           exec_remote(["kamal-backup", "restore", "production", snapshot, "--yes"])
@@ -229,7 +265,7 @@ module KamalBackup
 
       method_option :database, type: :string, desc: "Scratch database name for PostgreSQL or MySQL"
       method_option :"sqlite-path", type: :string, desc: "Scratch SQLite path for production-side drills"
-      method_option :files, type: :string, default: "/restore/files", desc: "Scratch files target for the drill"
+      method_option :files, type: :string, default: "/restore/files", desc: "Scratch Active Storage target for the drill"
       method_option :check, type: :string, desc: "Run a verification command after the restore"
       desc "production [SNAPSHOT]", "Run a restore drill on production infrastructure using scratch targets"
       def production(snapshot = "latest")
@@ -299,7 +335,7 @@ module KamalBackup
     class_option :config_file, aliases: "-c", type: :string, desc: "Path to Kamal deploy config file"
     class_option :destination, aliases: "-d", type: :string, desc: "Kamal destination to use"
     remove_command :tree
-    desc "restore SUBCOMMAND ...ARGS", "Restore a backup onto the local machine or into production"
+    desc "restore SUBCOMMAND ...ARGS", "Restore a database and Active Storage backup locally or into production"
     subcommand "restore", RestoreCLI
     desc "drill SUBCOMMAND ...ARGS", "Run a restore drill on the local machine or on production infrastructure"
     subcommand "drill", DrillCLI
@@ -323,7 +359,7 @@ module KamalBackup
 
     include Helpers
 
-    desc "backup", "Run one backup immediately"
+    desc "backup", "Run one database and Active Storage backup immediately"
     def backup
       if deployment_mode?
         exec_remote(["kamal-backup", "backup"])
@@ -350,7 +386,7 @@ module KamalBackup
       end
     end
 
-    desc "evidence", "Print redacted operational evidence as JSON"
+    desc "evidence", "Print redacted backup, check, and restore-drill evidence as JSON"
     def evidence
       if deployment_mode?
         exec_remote(["kamal-backup", "evidence"])
@@ -359,7 +395,18 @@ module KamalBackup
       end
     end
 
-    desc "init", "Create kamal-backup config stubs for local restore and drill commands"
+    desc "validate", "Validate backup configuration without running a backup"
+    def validate
+      if validate_deploy_mode?
+        validate_deploy_config
+      else
+        direct_app.validate
+      end
+
+      puts("ok")
+    end
+
+    desc "init", "Create config and print the scheduled backup accessory snippet"
     def init
       write_init_file(shared_config_path, shared_config_template)
 
@@ -368,7 +415,8 @@ module KamalBackup
       puts
       puts deploy_snippet
       puts
-      puts "For most Rails apps, restore local and drill local can infer the development database, storage path, and tmp state directory."
+      puts "The accessory runs scheduled database and Active Storage backups with backup_schedule_seconds."
+      puts "For most Rails apps, restore local and drill local can infer the development database, Active Storage path, and tmp state directory."
       puts "Local restore and drill also require the restic binary on your machine."
       puts "Create config/kamal-backup.local.yml only if you need to override those local defaults."
     end

data/lib/kamal_backup/config.rb

@@ -14,7 +14,9 @@ module KamalBackup
     }.freeze
 
     SUSPICIOUS_BACKUP_PATHS = %w[/ /var /etc /root /usr /bin /sbin /boot /dev /proc /sys /run].freeze
-    DEFAULT_CONFIG_PATHS = %w[config/kamal-backup.yml config/kamal-backup.local.yml].freeze
+    SHARED_CONFIG_PATH = "config/kamal-backup.yml"
+    LOCAL_CONFIG_PATH = "config/kamal-backup.local.yml"
+    DEFAULT_CONFIG_PATHS = [SHARED_CONFIG_PATH, LOCAL_CONFIG_PATH].freeze
     YAML_KEY_ALIASES = {
       "app_name" => "APP_NAME",
       "database_adapter" => "DATABASE_ADAPTER",
@@ -24,7 +26,10 @@ module KamalBackup
       "local_restore_source_paths" => "LOCAL_RESTORE_SOURCE_PATHS",
       "accessory" => "KAMAL_BACKUP_ACCESSORY",
       "restic_repository" => "RESTIC_REPOSITORY",
+      "restic_repository_file" => "RESTIC_REPOSITORY_FILE",
       "restic_password" => "RESTIC_PASSWORD",
+      "restic_password_file" => "RESTIC_PASSWORD_FILE",
+      "restic_password_command" => "RESTIC_PASSWORD_COMMAND",
       "restic_init_if_missing" => "RESTIC_INIT_IF_MISSING",
       "restic_check_after_backup" => "RESTIC_CHECK_AFTER_BACKUP",
       "restic_check_read_data_subset" => "RESTIC_CHECK_READ_DATA_SUBSET",
@@ -45,9 +50,10 @@ module KamalBackup
 
     attr_reader :env
 
-    def initialize(env: ENV, cwd: Dir.pwd, defaults: {})
+    def initialize(env: ENV, cwd: Dir.pwd, defaults: {}, config_paths: nil, load_project_defaults: true)
       raw_env = env.to_h
-      @env = project_defaults(cwd: cwd).merge(defaults.to_h).merge(load_config_files(raw_env, cwd: cwd)).merge(raw_env)
+      base = load_project_defaults ? project_defaults(cwd: cwd) : {}
+      @env = base.merge(defaults.to_h).merge(load_config_files(raw_env, cwd: cwd, paths: config_paths)).merge(raw_env)
     end
 
     def app_name
@@ -66,10 +72,22 @@ module KamalBackup
       value("RESTIC_REPOSITORY")
     end
 
+    def restic_repository_file
+      value("RESTIC_REPOSITORY_FILE")
+    end
+
     def restic_password
       value("RESTIC_PASSWORD")
     end
 
+    def restic_password_file
+      value("RESTIC_PASSWORD_FILE")
+    end
+
+    def restic_password_command
+      value("RESTIC_PASSWORD_COMMAND")
+    end
+
     def restic_init_if_missing?
       truthy?("RESTIC_INIT_IF_MISSING")
     end
@@ -176,16 +194,16 @@ module KamalBackup
       end
     end
 
-    def validate_restic
+    def validate_restic(check_files: true)
       required_app_name
-      required_value("RESTIC_REPOSITORY")
-      required_value("RESTIC_PASSWORD")
+      validate_restic_repository(check_files: check_files)
+      validate_restic_password(check_files: check_files)
     end
 
-    def validate_backup
-      validate_restic
-      validate_database_backup
-      validate_backup_paths
+    def validate_backup(check_files: true)
+      validate_restic(check_files: check_files)
+      validate_database_backup(check_files: check_files)
+      validate_backup_paths(check_files: check_files)
     end
 
     def validate_local_machine_restore
@@ -193,7 +211,7 @@ module KamalBackup
       validate_local_machine_paths
     end
 
-    def validate_database_backup
+    def validate_database_backup(check_files: true)
       case database_adapter
       when "postgres"
         unless value("DATABASE_URL") || value("PGDATABASE")
@@ -205,13 +223,13 @@ module KamalBackup
         end
       when "sqlite"
         path = required_value("SQLITE_DATABASE_PATH")
-        raise ConfigurationError, "SQLITE_DATABASE_PATH does not exist: #{path}" unless File.file?(path)
+        raise ConfigurationError, "SQLITE_DATABASE_PATH does not exist: #{path}" if check_files && !File.file?(path)
       else
         raise ConfigurationError, "DATABASE_ADAPTER is required or must be detectable from DATABASE_URL/SQLITE_DATABASE_PATH"
       end
     end
 
-    def validate_backup_paths
+    def validate_backup_paths(check_files: true)
       paths = backup_paths
       raise ConfigurationError, "BACKUP_PATHS must contain at least one path" if paths.empty?
 
@@ -220,7 +238,7 @@ module KamalBackup
         if SUSPICIOUS_BACKUP_PATHS.include?(expanded) && !allow_suspicious_backup_paths?
           raise ConfigurationError, "refusing suspicious backup path #{expanded}; set KAMAL_BACKUP_ALLOW_SUSPICIOUS_PATHS=true to override"
         end
-        raise ConfigurationError, "backup path does not exist: #{path}" unless File.exist?(path)
+        raise ConfigurationError, "backup path does not exist: #{path}" if check_files && !File.exist?(path)
       end
     end
 
@@ -288,22 +306,48 @@ module KamalBackup
         RailsApp.new(cwd: cwd).defaults
       end
 
-      def load_config_files(raw_env, cwd:)
-        config_paths(raw_env, cwd: cwd).each_with_object({}) do |path, merged|
+      def load_config_files(raw_env, cwd:, paths:)
+        config_paths(raw_env, cwd: cwd, paths: paths).each_with_object({}) do |path, merged|
           next unless File.file?(path)
 
           merged.merge!(normalize_config_file(path))
         end
       end
 
-      def config_paths(raw_env, cwd:)
-        if explicit = raw_env["KAMAL_BACKUP_CONFIG"]
+      def config_paths(raw_env, cwd:, paths:)
+        if paths
+          Array(paths).map { |path| File.expand_path(path, cwd) }
+        elsif explicit = raw_env["KAMAL_BACKUP_CONFIG"]
           [File.expand_path(explicit, cwd)]
         else
           DEFAULT_CONFIG_PATHS.map { |relative| File.expand_path(relative, cwd) }
         end
       end
 
+      def validate_restic_repository(check_files:)
+        return if restic_repository
+
+        if path = restic_repository_file
+          raise ConfigurationError, "RESTIC_REPOSITORY_FILE does not exist: #{path}" if check_files && !File.file?(path)
+
+          return
+        end
+
+        raise ConfigurationError, "RESTIC_REPOSITORY or RESTIC_REPOSITORY_FILE is required"
+      end
+
+      def validate_restic_password(check_files:)
+        return if restic_password || restic_password_command
+
+        if path = restic_password_file
+          raise ConfigurationError, "RESTIC_PASSWORD_FILE does not exist: #{path}" if check_files && !File.file?(path)
+
+          return
+        end
+
+        raise ConfigurationError, "RESTIC_PASSWORD, RESTIC_PASSWORD_FILE, or RESTIC_PASSWORD_COMMAND is required"
+      end
+
       def normalize_config_file(path)
         data = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
         return {} if data.nil?

data/lib/kamal_backup/kamal_bridge.rb

@@ -4,6 +4,7 @@ require_relative "command"
 module KamalBackup
   class KamalBridge
     DEFAULT_CONFIG_FILE = "config/deploy.yml"
+    VERSION_LINE_PATTERN = /\A\d+(?:\.\d+)+(?:[-.][A-Za-z0-9]+)*\z/
 
     def initialize(redactor:, config_file: nil, destination: nil)
       @redactor = redactor
@@ -42,13 +43,17 @@ module KamalBackup
       end
     end
 
+    def accessory_environment(accessory_name:)
+      accessory_secret_placeholders(accessory_name).merge(accessory_clear_env(accessory_name))
+    end
+
     def execute_on_accessory(accessory_name:, command:)
       capture_kamal(kamal_exec_argv(accessory_name, command))
     end
 
     def remote_version(accessory_name:)
       result = execute_on_accessory(accessory_name: accessory_name, command: "kamal-backup version")
-      version = result.stdout.to_s.strip
+      version = parse_version_line(result.stdout)
 
       if version.empty?
         raise ConfigurationError, "could not determine remote kamal-backup version from accessory #{accessory_name}"
@@ -71,13 +76,23 @@ module KamalBackup
       end
 
       def accessory_clear_env(accessory_name)
-        accessory = accessories.fetch(accessory_name) do
+        normalize_env(fetch(accessory_env(accessory_name), :clear) || {})
+      end
+
+      def accessory_secret_placeholders(accessory_name)
+        normalize_secret_env(fetch(accessory_env(accessory_name), :secret))
+      end
+
+      def accessory_env(accessory_name)
+        fetch(accessory(accessory_name), :env) || {}
+      end
+
+      def accessory(accessory_name)
+        accessories.fetch(accessory_name) do
           accessories.fetch(accessory_name.to_sym) do
             raise ConfigurationError, "accessory #{accessory_name.inspect} is not defined in #{config_file || DEFAULT_CONFIG_FILE}"
           end
         end
-
-        normalize_env(fetch(fetch(accessory, :env) || {}, :clear) || {})
       end
 
       def normalize_env(values)
@@ -86,6 +101,19 @@ module KamalBackup
         end
       end
 
+      def normalize_secret_env(values)
+        case values
+        when Hash
+          values.each_with_object({}) { |(key, _value), env| env[key.to_s] = "configured" }
+        when Array
+          values.each_with_object({}) { |key, env| env[key.to_s] = "configured" }
+        when String, Symbol
+          { values.to_s => "configured" }
+        else
+          {}
+        end
+      end
+
       def fetch(hash, key)
         hash[key] || hash[key.to_s] || hash[key.to_sym]
       end
@@ -127,5 +155,9 @@ module KamalBackup
           Command.capture(spec, redactor: @redactor)
         end
       end
+
+      def parse_version_line(output)
+        output.to_s.lines.map(&:strip).reverse.find { |line| line.match?(VERSION_LINE_PATTERN) }.to_s
+      end
   end
 end

data/lib/kamal_backup/restic.rb

@@ -6,6 +6,8 @@ require_relative "command"
 
 module KamalBackup
   class Restic
+    RESTIC_ENV_PATTERN = /\A(?:RESTIC_|AWS_|B2_|AZURE_|GOOGLE_|RCLONE_|OS_|ST_|HP_|HTTP_|HTTPS_|NO_PROXY)/i
+
     attr_reader :config, :redactor
 
     def initialize(config, redactor:)
@@ -25,13 +27,19 @@ module KamalBackup
     end
 
     def backup_stream(command, filename:, tags:)
-      restic_command = CommandSpec.new(argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags))
+      restic_command = CommandSpec.new(
+        argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags),
+        env: restic_env
+      )
       log("backing up stream as #{filename}")
       pipe_commands(command, restic_command, producer_label: "dump", consumer_label: "restic backup")
     end
 
     def backup_file(path, filename:, tags:)
-      command = CommandSpec.new(argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags))
+      command = CommandSpec.new(
+        argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags),
+        env: restic_env
+      )
       log("backing up file content as #{filename}")
 
       File.open(path, "rb") do |file|
@@ -126,12 +134,12 @@ module KamalBackup
     end
 
     def pipe_dump_to_command(snapshot, filename, command)
-      restic_command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename])
+      restic_command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename], env: restic_env)
       pipe_commands(restic_command, command, producer_label: "restic dump", consumer_label: command.argv.first)
     end
 
     def write_dump_to_path(snapshot, filename, target_path)
-      command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename])
+      command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename], env: restic_env)
       target_path = File.expand_path(target_path)
       FileUtils.mkdir_p(File.dirname(target_path))
       temp_path = "#{target_path}.kamal-backup-#{$$}.tmp"
@@ -160,7 +168,7 @@ module KamalBackup
     end
 
     def run(args)
-      Command.capture(CommandSpec.new(argv: ["restic"] + args), redactor: redactor)
+      Command.capture(CommandSpec.new(argv: ["restic"] + args, env: restic_env), redactor: redactor)
     end
 
     def common_tags
@@ -172,6 +180,12 @@ module KamalBackup
         tags.compact.each_with_object([]) { |tag, args| args.concat(["--tag", tag]) }
       end
 
+      def restic_env
+        config.env.each_with_object({}) do |(key, value), env|
+          env[key] = value if key.to_s.match?(RESTIC_ENV_PATTERN)
+        end
+      end
+
       def pipe_commands(producer, consumer, producer_label:, consumer_label:)
         Open3.popen3(producer.env, *producer.argv) do |producer_stdin, producer_stdout, producer_stderr, producer_wait|
           producer_stdin.close

data/lib/kamal_backup/version.rb

@@ -1,3 +1,3 @@
 module KamalBackup
-  VERSION = "0.1.2"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.1
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -38,8 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Back up PostgreSQL, MySQL, SQLite, and mounted Rails file data into restic,
-  then run deliberate restores and restore drills.
+description: Back up PostgreSQL, MySQL, SQLite, and file-backed Active Storage files
+  into restic on a schedule, then run restore drills and produce review evidence.
 email:
 executables:
 - kamal-backup
@@ -92,5 +92,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Rails-friendly encrypted backups and restore drills for Kamal apps
+summary: Scheduled backups, restore drills, and evidence for Rails apps deployed with
+  Kamal
 test_files: []