kamal-backup 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b93c203599481320559eb006ccf07a07c010c5bc4d5dfcae3e11b7a9a832fa3
-  data.tar.gz: 705fc119fcacdd54ee431e9cfb5b88220a0faae02540cba77e38c45b94044905
+  metadata.gz: 0442e12748359ee182d6fc91e5573375440c31a5a65ccf1b46079547b8e4bc21
+  data.tar.gz: 9af03ddf3ad23b99b77c717711dc66cde34bc17500e66e776aff50ca2678e653
 SHA512:
-  metadata.gz: fd7b30595fe843980d39979b8b7e241fbd54c7fd814c55bccb4bfcdf6b175b5767e84910929050f4e3aa40f150aec5b01e15015b196e522e3c48566f9527020f
-  data.tar.gz: e81f5d21997f6f072b9556a73b7e751accbe99098adaebaec3435ca15600e8d13f204b9d343cc3ae7f6905a86efd3abea3c5dd0d64ea602bd2f2617d8bca8fef
+  metadata.gz: ccd324da250d8a36f623a6c65c9cf000c80e4fbcc0308944c1074c67ce9422e1e637c55e672160399078944c83c281ccec25ff17a63d1181ed28045244a2d674
+  data.tar.gz: 80f64be478843d1695cdfa34c899ba614ee7ed45a10853f521c08ee568f003f3b0045809ef1ff0c1217e5ec834d2a607888963998af64f9643886048f0e65bf1

data/README.md

@@ -68,11 +68,13 @@ accessories:
         - AWS_ACCESS_KEY_ID
         - AWS_SECRET_ACCESS_KEY
     volumes:
-      - "chatwithwork_storage:/data/storage:ro"
+      - "chatwithwork_storage:/data/storage"
       - "chatwithwork_backup_state:/var/lib/kamal-backup"
 ```
 
-For SQLite databases stored on the mounted storage volume, omit `:ro` from that volume.
+The storage volume is writable so `restore production` can replace its contents safely without replacing the mount
+point. Writable access is also required for SQLite databases stored on that volume. For a backup-only accessory,
+you can append `:ro`; remove it and reboot the accessory before a production file restore.
 When the configured SQLite database file lives under a configured file backup path, `kamal-backup` excludes the raw database, WAL, and shared-memory files from the restic file snapshot automatically.
 
 Put the backup settings in `config/kamal-backup.yml`:
@@ -97,6 +99,8 @@ backup:
   schedule: 1d
 ```
 
+Only paths explicitly listed under `paths` are included in file snapshots. Omit `paths` for a database-only backup; `kamal-backup` never infers `storage` from Rails.
+
 Boot it. The container runs `kamal-backup schedule` by default:
 
 ```sh

data/lib/kamal_backup/app.rb

@@ -58,8 +58,8 @@ module KamalBackup
 
       build_restore_result('local', snapshot) do |result|
         databases.each { |adapter| validate_local_machine_database_target(adapter) }
-        result[:databases] = perform_database_restores_to_current(snapshot)
         result[:files] = perform_replacement_file_restore(snapshot, production_source: false)
+        result[:databases] = perform_database_restores_to_current(snapshot)
       end
     end
 
@@ -67,8 +67,8 @@ module KamalBackup
       validate_production_restore
 
       build_restore_result('production', snapshot) do |result|
-        result[:databases] = perform_database_restores_to_current(snapshot)
         result[:files] = perform_replacement_file_restore(snapshot, production_source: true)
+        result[:databases] = perform_database_restores_to_current(snapshot)
       end
     end
 
@@ -77,8 +77,8 @@ module KamalBackup
 
       run_drill('local', snapshot, check_command: check_command) do |result|
         databases.each { |adapter| validate_local_machine_database_target(adapter) }
-        result[:databases] = perform_database_restores_to_current(snapshot)
         result[:files] = perform_replacement_file_restore(snapshot, production_source: false)
+        result[:databases] = perform_database_restores_to_current(snapshot)
       end
     end
 
@@ -87,6 +87,7 @@ module KamalBackup
       validate_production_drill(file_target, database_name, sqlite_path)
 
       run_drill('production', snapshot, check_command: check_command) do |result|
+        result[:files] = perform_file_restore(snapshot, target: file_target)
         result[:databases] = databases.map do |adapter|
           perform_database_restore_to_scratch(
             snapshot,
@@ -95,7 +96,6 @@ module KamalBackup
             sqlite_path: sqlite_path
           )
         end
-        result[:files] = perform_file_restore(snapshot, target: file_target)
       end
     end
 
@@ -374,6 +374,8 @@ module KamalBackup
     end
 
     def perform_replacement_file_restore(snapshot, production_source:)
+      return nil if config.backup_paths.empty?
+
       source_paths = production_source ? config.backup_paths : config.local_restore_source_paths
       target_paths = config.backup_paths
       resolved_snapshot = resolve_snapshot(snapshot, tags: ['type:files'])
@@ -390,20 +392,52 @@ module KamalBackup
     end
 
     def replace_target_paths(stage_dir, source_paths:, target_paths:)
-      source_paths.zip(target_paths).each do |source_path, target_path|
+      path_pairs = source_paths.zip(target_paths)
+      validate_replacement_paths(stage_dir, path_pairs)
+
+      path_pairs.each do |source_path, target_path|
         replace_target_path(stage_dir, source_path, target_path)
       end
     end
 
+    def validate_replacement_paths(stage_dir, path_pairs)
+      path_pairs.each do |source_path, target_path|
+        source = staged_backup_path(stage_dir, source_path)
+        raise ConfigurationError, "restored file snapshot is missing #{source_path}" unless File.exist?(source)
+
+        ensure_writable_restore_target(target_path)
+      end
+    end
+
     def replace_target_path(stage_dir, source_path, target_path)
       source = staged_backup_path(stage_dir, source_path)
       target = File.expand_path(target_path)
 
       raise ConfigurationError, "restored file snapshot is missing #{source_path}" unless File.exist?(source)
 
-      FileUtils.rm_rf(target)
-      FileUtils.mkdir_p(File.dirname(target))
-      FileUtils.mv(source, target)
+      if File.directory?(source) && File.directory?(target) && !File.symlink?(target)
+        replace_directory_contents(source, target)
+      else
+        FileUtils.remove_entry(target) if File.exist?(target) || File.symlink?(target)
+        FileUtils.mkdir_p(File.dirname(target))
+        FileUtils.mv(source, target)
+      end
+    rescue Errno::EACCES, Errno::EPERM, Errno::EROFS => e
+      raise ConfigurationError, "cannot restore files to #{target}: target must be writable (#{e.message})"
+    end
+
+    def ensure_writable_restore_target(target_path)
+      target = File.expand_path(target_path)
+      return unless File.directory?(target) && !File.symlink?(target)
+
+      Dir.mktmpdir('.kamal-backup-write-test-', target) {}
+    rescue Errno::EACCES, Errno::EPERM, Errno::EROFS => e
+      raise ConfigurationError, "cannot restore files to #{target}: target must be writable (#{e.message})"
+    end
+
+    def replace_directory_contents(source, target)
+      Dir.children(target).each { |entry| FileUtils.remove_entry(File.join(target, entry)) }
+      Dir.children(source).each { |entry| FileUtils.mv(File.join(source, entry), target) }
     end
 
     def staged_backup_path(stage_dir, path)
@@ -411,6 +445,8 @@ module KamalBackup
     end
 
     def perform_file_restore(snapshot, target:)
+      return nil if config.backup_paths.empty?
+
       resolved_snapshot = resolve_snapshot(snapshot, tags: ['type:files'])
       validated_target = config.validate_file_restore_target(target)
       restic.restore_snapshot(resolved_snapshot, validated_target)
@@ -436,7 +472,7 @@ module KamalBackup
     def validate_production_drill(file_target, database_name, sqlite_path)
       config.validate_restic
       config.validate_database_backup
-      config.validate_file_restore_target(file_target)
+      config.validate_file_restore_target(file_target) if config.backup_paths.any?
 
       databases.each do |adapter|
         case adapter.adapter_name

data/lib/kamal_backup/cli/helpers.rb

@@ -289,7 +289,7 @@ module KamalBackup
                   - AWS_ACCESS_KEY_ID
                   - AWS_SECRET_ACCESS_KEY
               volumes:
-                - "your_app_storage:/data/storage:ro"
+                - "your_app_storage:/data/storage"
                 - "your_app_backup_state:/var/lib/kamal-backup"
         YAML
       end

data/lib/kamal_backup/cli.rb

@@ -26,15 +26,15 @@ module KamalBackup
         CLI.basename
       end
 
-      desc 'local [SNAPSHOT]', 'Restore the backup into the local database and Active Storage path'
+      desc 'local [SNAPSHOT]', 'Restore the backup into the local database and configured file paths'
       def local(snapshot = 'latest')
-        confirm!("Restore #{snapshot} into the local database and Active Storage path? This will overwrite local data.")
+        confirm!("Restore #{snapshot} into the local database and configured file paths? This will overwrite local data.")
         puts(JSON.pretty_generate(local_restore_app.restore_to_local_machine(snapshot)))
       end
 
       method_option :"confirm-production-restore", type: :boolean, default: false,
                                                    desc: 'Confirm production restore without interactive prompts'
-      desc 'production [SNAPSHOT]', 'Restore the backup into the production database and Active Storage path'
+      desc 'production [SNAPSHOT]', 'Restore the backup into the production database and configured file paths'
       def production(snapshot = 'latest')
         confirm_production_restore!(snapshot)
 
@@ -133,7 +133,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 database and Active Storage backup locally or into production'
+    desc 'restore SUBCOMMAND ...ARGS', 'Restore database and configured file backups 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
@@ -162,7 +162,7 @@ module KamalBackup
 
     method_option :force, type: :boolean, default: false,
                           desc: 'Run a backup even if the configured schedule is not due'
-    desc 'backup', 'Run a due database and Active Storage backup'
+    desc 'backup', 'Run a due database and configured file backup'
     def backup
       if remote_command_mode?
         argv = %w[kamal-backup backup]
@@ -238,10 +238,11 @@ module KamalBackup
       puts
       puts deploy_snippet
       puts
-      puts 'The accessory runs scheduled database and file backups with backup.schedule.'
-      puts 'For most Rails apps, restore local and drill local can infer the development database, Active Storage path, and tmp state directory.'
+      puts 'The accessory runs scheduled database and configured file backups with backup.schedule.'
+      puts 'File backups run only for paths explicitly configured in config/kamal-backup.yml.'
+      puts 'Rails local restores infer the development database and tmp state directory, but never file paths.'
       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.'
+      puts 'When production paths are configured, set their local targets in config/kamal-backup.local.yml.'
     end
 
     desc 'schedule', 'Run the foreground scheduler loop'

data/lib/kamal_backup/config.rb

@@ -214,7 +214,10 @@ module KamalBackup
       source_paths = local_restore_source_paths
       target_paths = backup_paths
 
-      raise ConfigurationError, 'local restore source paths must contain the same number of paths as file paths' unless source_paths.size == target_paths.size
+      unless source_paths.size == target_paths.size
+        raise ConfigurationError,
+              'local file paths must be explicitly configured and match the number of production restore source paths'
+      end
 
       source_paths.zip(target_paths)
     end

data/lib/kamal_backup/rails_app.rb

@@ -22,9 +22,6 @@ module KamalBackup
       {}.tap do |defaults|
         defaults.merge!(deploy_defaults)
         defaults.merge!(database_defaults)
-
-        defaults['BACKUP_PATHS'] = local_storage_path if local_storage_path
-
         defaults['KAMAL_BACKUP_STATE_DIR'] = File.join(@cwd, 'tmp', 'kamal-backup')
       end
     end
@@ -90,10 +87,6 @@ module KamalBackup
       end
     end
 
-    def local_storage_path
-      File.join(@cwd, 'storage')
-    end
-
     def local_database_config
       environment = fetch(parsed_yaml(database_config_path), DEVELOPMENT_ENV)
       return nil unless environment.is_a?(Hash)

data/lib/kamal_backup/restic.rb

@@ -28,13 +28,12 @@ module KamalBackup
     end
 
     def backup_stream(command, filename:, tags:)
-      restic_command = CommandSpec.new(
-        argv: %w[restic
-                 backup] + host_args + ['--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')
+      run(
+        ['backup'] + host_args + ['--stdin-filename', filename] + tag_args(common_tags + tags) +
+          ['--stdin-from-command', '--'] + command.argv,
+        env: restic_env.merge(command.env)
+      )
     end
 
     def backup_file(path, filename:, tags:)
@@ -211,9 +210,9 @@ module KamalBackup
 
     private
 
-    def run(args, log_output: true)
+    def run(args, log_output: true, env: restic_env)
       Command.capture(
-        CommandSpec.new(argv: ['restic'] + args, env: restic_env),
+        CommandSpec.new(argv: ['restic'] + args, env: env),
         redactor: redactor,
         log_output: log_output
       )

data/lib/kamal_backup/scheduler.rb

@@ -24,7 +24,7 @@ module KamalBackup
           @backup_block.call
           log("backup completed at #{Time.now.utc.iso8601}")
         rescue StandardError => e
-          warn("[kamal-backup] backup failed at #{Time.now.utc.iso8601}: #{e.class}: #{e.message}")
+          warn("ERROR [kamal-backup] backup failed at #{Time.now.utc.iso8601}: #{e.class}: #{e.message}")
         end
 
         sleep_interruptibly(@config.backup_schedule_seconds)
@@ -49,7 +49,7 @@ module KamalBackup
     end
 
     def log(message)
-      $stdout.puts("[kamal-backup] #{message}")
+      $stdout.puts("INFO [kamal-backup] #{message}")
     end
   end
 end

data/lib/kamal_backup/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KamalBackup
-  VERSION = '0.4.0'
+  VERSION = '0.4.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor