kamal-backup 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 801ab5f224e1e018805b65650da3c0946d6c785eb8b2a3e3e3256bcf97649abb
-  data.tar.gz: 60e98bfe053103b3405d483902a167ee2d86f7a723448e06eacb2937b56fd4d3
+  metadata.gz: 2402ed466c957ae450d1e3196018d7099da3e01c59e7cc27e0a8dd7db0dbec5b
+  data.tar.gz: 43d46f5648d0a2e410ea3fee13876a65c032b42a7260adb7a9210f8e8452ae6c
 SHA512:
-  metadata.gz: b1dbd9a03222917490629d56a4bfca69e1abbac79ed241bf480ba0da50453e67e1224dcf5f6d315ce23039b31febe2d449300dae167ddf19e627decd07c6116e
-  data.tar.gz: c4392a6048ceea5ec81b20cedad84f15d864ecb37a83337571cc857de8c730c0a84629df335e9b6c4f273868ad86a6ddcc631c00315ff8ff965ac0230bcf1f5a
+  metadata.gz: 645f1b5d3a0da81237a3391efde6f22747447b93504580693ebe2dd0e7fb2d81024a00d54d427890992234687034948b25053d741e8a974ee379a385b9e6a9d3
+  data.tar.gz: 83577eddd32f3cd423408fea71c75769138d5b67041d555b369478129f20045eea2d51fd031b45067e6862a53dc6b4a2f7218a374e57a879d9ff606a41258c2d

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`:
@@ -111,6 +113,7 @@ Run the first backup, check the repository, and print evidence. From an app chec
 bundle exec kamal-backup backup
 bundle exec kamal-backup list
 bundle exec kamal-backup check
+bundle exec kamal-backup unlock
 bundle exec kamal-backup evidence
 ```
 

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
 
@@ -109,6 +109,11 @@ module KamalBackup
       restic.check.stdout
     end
 
+    def unlock
+      config.validate_restic
+      restic.unlock.stdout
+    end
+
     def prune
       config.validate_backup(check_files: false)
       restic.prune
@@ -369,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'])
@@ -385,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)
@@ -406,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)
@@ -431,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

@@ -191,6 +191,15 @@ module KamalBackup
       end
     end
 
+    desc 'unlock', 'Clear stale restic repository locks'
+    def unlock
+      if remote_command_mode?
+        exec_remote(%w[kamal-backup unlock])
+      else
+        print(direct_app.unlock)
+      end
+    end
+
     desc 'prune', 'Apply the configured restic retention policy and prune unneeded data'
     def prune
       if remote_command_mode?

data/lib/kamal_backup/command.rb

@@ -174,12 +174,13 @@ module KamalBackup
       end
 
       def command_failure(spec, status, stdout, stderr, redactor)
+        redacted_stderr = redactor.redact_string(stderr)
         CommandError.new(
-          "command failed (#{status}): #{spec.display(redactor)}\n#{redactor.redact_string(stderr)}",
+          "command failed (#{status}): #{spec.display(redactor)}\n#{redacted_stderr}#{restic_lock_hint(spec, stderr)}",
           command: spec,
           status: status,
           stdout: redactor.redact_string(stdout),
-          stderr: redactor.redact_string(stderr)
+          stderr: redacted_stderr
         )
       end
 
@@ -191,6 +192,14 @@ module KamalBackup
           stderr: error.message
         )
       end
+
+      def restic_lock_hint(spec, stderr)
+        return '' unless spec.argv.first == 'restic'
+        return '' if spec.argv[1] == 'unlock'
+        return '' unless stderr.to_s.match?(/repository is already locked|unlock.+stale locks/i)
+
+        "\nHint: run `kamal-backup unlock` to clear stale restic locks, then retry the command."
+      end
     end
   end
 end

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:)
@@ -99,6 +98,11 @@ module KamalBackup
       end
     end
 
+    def unlock
+      log('clearing stale restic locks')
+      run(%w[unlock])
+    end
+
     def check
       args = %w[check]
       args.concat(['--read-data-subset', config.check_read_data_subset]) if config.check_read_data_subset
@@ -206,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.3.1'
+  VERSION = '0.4.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.1
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor