feat: add container stop/restart for docker volume backups

- Add ContainerStopConfig with stopContainers, stopTimeout,
  restartRetries, and restartRetryDelay options
- Support global config (docker.containerStop) and per-volume override
- Add CLI flags: --stop-containers, --stop-timeout, --restart-retries
- Detect auto-restart policies and warn about potential conflicts
- Retry failed restarts with configurable attempts and delay
- Add comprehensive tests for all new functionality

Author: adiologydev

CLAUDE.md

@@ -90,11 +90,13 @@ Run tests: `bun test`
 ## CI/CD
 
 CI runs on push/PR to main (`.github/workflows/ci.yml`):
+
 1. Type check: `bunx tsc --noEmit`
 2. Lint: `bun run lint`
 3. Test: `bun test`
 
 Release runs on version tags (`.github/workflows/release.yml`):
+
 1. Same checks as CI
 2. Build binaries for linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64
 3. Generate SHA256 checksums
@@ -120,6 +122,7 @@ bun run build:windows-x64  # Windows x64
 - `js-yaml` - YAML config parsing
 
 Dev:
+
 - `oxlint` - Linting
 - `oxfmt` - Formatting
 
@@ -132,6 +135,8 @@ Main config interface is `BackitupConfig` in `src/types/config.ts`:
 - `s3: S3StorageConfig` - S3/R2/MinIO settings
 - `schedules: Record<string, ScheduleConfig>` - Cron schedules with retention
 - `docker?: DockerConfig` - Docker volume backup settings
+  - `containerStop?: ContainerStopConfig` - Global container stop/restart settings
+  - `volumes[].containerStop?: ContainerStopConfig` - Per-volume override
 
 ## Common Tasks
 

README.md

@@ -231,6 +231,10 @@ Override config file settings directly from the command line. Useful for quick b
 | **Docker**        | `--docker`                     | Enable Docker volume backups                 |
 |                   | `--no-docker`                  | Disable Docker volume backups                |
 |                   | `--docker-volume <name>`       | Docker volume to backup (can be repeated)    |
+|                   | `--stop-containers`            | Stop containers before volume backup         |
+|                   | `--no-stop-containers`         | Don't stop containers (default)              |
+|                   | `--stop-timeout <seconds>`     | Timeout for graceful stop (default: 30)      |
+|                   | `--restart-retries <n>`        | Retry attempts for restart (default: 3)      |
 
 ### Examples
 
@@ -306,6 +310,14 @@ version: "1.0"
 
 docker:
   enabled: true
+
+  # Global container stop settings (optional)
+  containerStop:
+    stopContainers: true      # Stop containers before backup
+    stopTimeout: 30           # Seconds to wait for graceful stop
+    restartRetries: 3         # Retry attempts if restart fails
+    restartRetryDelay: 1000   # Milliseconds between retries
+
   volumes:
     # Direct volume name
     - name: postgres_data
@@ -315,14 +327,42 @@ docker:
       type: compose
       composePath: ./docker-compose.yml
       projectName: myapp  # Optional, inferred from directory
+
+    # Per-volume container stop override
+    - name: redis_data
+      containerStop:
+        stopContainers: false  # Override: don't stop for this volume
 ```
 
 ### How It Works
 
 1. BackItUp uses a temporary Alpine container to create the backup
 2. The volume is mounted read-only to ensure data safety
-3. If a volume is in use by running containers, backup proceeds with a warning
-4. Each volume produces a separate archive: `backitup-volume-{name}-{schedule}-{timestamp}.tar.gz`
+3. If `stopContainers` is enabled:
+   - Containers using the volume are gracefully stopped before backup
+   - After backup completes, containers are automatically restarted
+   - Failed restarts are retried according to `restartRetries` setting
+4. If a volume is in use by running containers without stopping, backup proceeds with a warning
+5. Each volume produces a separate archive: `backitup-volume-{name}-{schedule}-{timestamp}.tar.gz`
+
+### Container Stop/Restart
+
+For data consistency (especially with databases), you can stop containers before backing up their volumes:
+
+```bash
+# Stop containers before backup (CLI)
+backitup backup -s daily --docker-volume postgres_data --stop-containers --local-path /backups
+
+# With custom timeout and retries
+backitup backup -s daily --docker-volume postgres_data \
+  --stop-containers --stop-timeout 60 --restart-retries 5 \
+  --local-path /backups
+```
+
+**Important notes:**
+- Containers with `restart: always` or `restart: unless-stopped` policies may auto-restart after being stopped. BackItUp detects this and logs a warning.
+- If a container fails to restart after all retries, the backup still succeeds but a warning is logged.
+- Per-volume settings override global settings, allowing fine-grained control.
 
 ### Docker Compose Integration
 

docs/commands/backup.md

@@ -50,6 +50,10 @@ Override or provide configuration without a config file:
 | `--docker`                     | Enable Docker volume backups                  |
 | `--no-docker`                  | Disable Docker volume backups                 |
 | `--docker-volume <name>`       | Docker volume to backup (repeatable)          |
+| `--stop-containers`            | Stop containers before volume backup          |
+| `--no-stop-containers`         | Don't stop containers (default)               |
+| `--stop-timeout <seconds>`     | Timeout for graceful stop (default: 30)       |
+| `--restart-retries <n>`        | Retry attempts for restart (default: 3)       |
 
 ## Schedules
 
@@ -109,6 +113,34 @@ backitup backup -s manual --skip-volumes
 backitup backup -s manual --volume postgres_data --volume redis_data
 ```
 
+### Docker Volume Backups with Container Stop
+
+For data consistency (especially with databases), stop containers before backing up their volumes:
+
+```bash
+# Stop containers, backup, then restart
+backitup backup -s manual --volumes-only --stop-containers
+
+# Inline volume backup with container stop
+backitup backup -s manual \
+  --docker-volume postgres_data \
+  --stop-containers \
+  --local-path /backups
+
+# With custom timeout and retries
+backitup backup -s manual \
+  --docker-volume postgres_data \
+  --stop-containers \
+  --stop-timeout 60 \
+  --restart-retries 5 \
+  --local-path /backups
+```
+
+**Notes:**
+- Containers are automatically restarted after backup completes
+- Containers with `restart: always` policy may auto-restart (a warning is logged)
+- If restart fails after all retries, backup succeeds but a warning is logged
+
 ### Config-Free Mode
 
 Run without a config file by providing required inline options:

docs/configuration.md

@@ -105,12 +105,23 @@ safety:
 # Docker volume backup configuration (optional)
 docker:
   enabled: false
+
+  # Global container stop settings (optional)
+  # Stop containers before backup to ensure data consistency
+  containerStop:
+    stopContainers: false       # Whether to stop containers using the volume
+    stopTimeout: 30             # Seconds to wait for graceful stop
+    restartRetries: 3           # Number of restart attempts if restart fails
+    restartRetryDelay: 1000     # Milliseconds between retry attempts
+
   volumes:
     # Direct volume name
     - name: postgres_data
 
-    # Another volume
+    # Another volume with per-volume container stop override
     - name: redis_data
+      containerStop:
+        stopContainers: true    # Override: stop containers for this volume
 
     # Resolve volume from docker-compose.yml service name
     # - name: db
@@ -213,24 +224,42 @@ Safety features for cleanup operations.
 
 Docker volume backup configuration.
 
-| Field     | Type    | Required | Description                  |
-| --------- | ------- | -------- | ---------------------------- |
-| `enabled` | boolean | Yes      | Enable Docker volume backups |
-| `volumes` | array   | Yes\*    | List of volumes to backup    |
+| Field           | Type    | Required | Description                            |
+| --------------- | ------- | -------- | -------------------------------------- |
+| `enabled`       | boolean | Yes      | Enable Docker volume backups           |
+| `containerStop` | object  | No       | Global container stop/restart settings |
+| `volumes`       | array   | Yes\*    | List of volumes to backup              |
 
 \*Required when enabled.
 
+**Container Stop Settings (`containerStop`):**
+
+| Field               | Type    | Default | Description                               |
+| ------------------- | ------- | ------- | ----------------------------------------- |
+| `stopContainers`    | boolean | `false` | Stop containers before backup             |
+| `stopTimeout`       | number  | `30`    | Seconds to wait for graceful stop         |
+| `restartRetries`    | number  | `3`     | Number of restart attempts if fails       |
+| `restartRetryDelay` | number  | `1000`  | Milliseconds between restart retry        |
+
 **Volume Entry:**
 
-| Field         | Type   | Required | Description                                    |
-| ------------- | ------ | -------- | ---------------------------------------------- |
-| `name`        | string | Yes      | Volume name or Compose service name            |
-| `type`        | string | No       | `"volume"` (default) or `"compose"`            |
-| `composePath` | string | No\*     | Path to docker-compose.yml                     |
-| `projectName` | string | No       | Compose project name (inferred from directory) |
+| Field           | Type   | Required | Description                                    |
+| --------------- | ------ | -------- | ---------------------------------------------- |
+| `name`          | string | Yes      | Volume name or Compose service name            |
+| `type`          | string | No       | `"volume"` (default) or `"compose"`            |
+| `composePath`   | string | No\*     | Path to docker-compose.yml                     |
+| `projectName`   | string | No       | Compose project name (inferred from directory) |
+| `containerStop` | object | No       | Per-volume override of container stop settings |
 
 \*Required when `type: compose`.
 
+**Notes on Container Stop:**
+
+- When `stopContainers` is enabled, BackItUp stops all containers using the volume before backup and restarts them after.
+- Containers with `restart: always` or `restart: unless-stopped` policies may auto-restart after being stopped. BackItUp detects this and logs a warning.
+- Per-volume `containerStop` settings override global settings.
+- If a container fails to restart after all retries, the backup still succeeds but a warning is logged.
+
 ## Minimal Configuration
 
 ### YAML

docs/inline-config.md

@@ -64,11 +64,15 @@ BackItUp supports passing configuration options directly via command-line flags.
 
 ### Docker
 
-| Option                   | Description                          |
-| ------------------------ | ------------------------------------ |
-| `--docker`               | Enable Docker volume backups         |
-| `--no-docker`            | Disable Docker volume backups        |
-| `--docker-volume <name>` | Docker volume to backup (repeatable) |
+| Option                       | Description                               |
+| ---------------------------- | ----------------------------------------- |
+| `--docker`                   | Enable Docker volume backups              |
+| `--no-docker`                | Disable Docker volume backups             |
+| `--docker-volume <name>`     | Docker volume to backup (repeatable)      |
+| `--stop-containers`          | Stop containers before volume backup      |
+| `--no-stop-containers`       | Don't stop containers (default behavior)  |
+| `--stop-timeout <seconds>`   | Timeout for graceful stop (default: 30)   |
+| `--restart-retries <n>`      | Retry attempts for restart (default: 3)   |
 
 ## Usage Modes
 
@@ -169,6 +173,26 @@ backitup backup -s manual \
   --local-path /backups
 ```
 
+### Docker Volumes with Container Stop
+
+For data consistency (especially with databases), stop containers before backup:
+
+```bash
+# Stop containers before backup, restart after
+backitup backup -s manual \
+  --docker-volume postgres_data \
+  --stop-containers \
+  --local-path /backups
+
+# With custom timeout and retries
+backitup backup -s manual \
+  --docker-volume postgres_data \
+  --stop-containers \
+  --stop-timeout 60 \
+  --restart-retries 5 \
+  --local-path /backups
+```
+
 ### S3-Compatible Storage (MinIO, R2)
 
 ```bash

package.json

@@ -25,7 +25,7 @@
     "build:all": "bun run build:linux-x64 && bun run build:linux-arm64",
     "test": "bun test",
     "lint": "bunx oxlint --fix",
-    "format": "bunx oxfmt@latest --fix"
+    "format": "bunx oxfmt@latest"
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",

src/cli/commands/backup.ts

@@ -185,11 +185,48 @@ export async function backupCommand(args: string[]): Promise<number> {
         label: "Volume names",
         value: volumeNames,
       });
+
+      // Count containers that were stopped
+      const stoppedContainers = result.volumeBackups
+        .flatMap((v) => v.stoppedContainers || [])
+        .filter((name, i, arr) => arr.indexOf(name) === i); // dedupe
+      if (stoppedContainers.length > 0) {
+        summaryItems.push({
+          label: "Containers stopped",
+          value: stoppedContainers.join(", "),
+        });
+      }
+
+      // Check for failed restarts
+      const failedRestarts = result.volumeBackups
+        .flatMap((v) => v.failedToRestart || [])
+        .filter((name, i, arr) => arr.indexOf(name) === i); // dedupe
+      if (failedRestarts.length > 0) {
+        summaryItems.push({
+          label: "Failed to restart",
+          value: `${failedRestarts.join(", ")} (manual restart required)`,
+        });
+      }
+
+      // Check for auto-restart warnings
+      const hadAutoRestartWarning = result.volumeBackups.some((v) => v.hadAutoRestartWarning);
+      if (hadAutoRestartWarning) {
+        summaryItems.push({
+          label: "Warning",
+          value: "Some containers had auto-restart policy",
+        });
+      }
+
       const inUseCount = result.volumeBackups.filter((v) => v.wasInUse).length;
-      if (inUseCount > 0) {
+      const stoppedCount = result.volumeBackups.filter(
+        (v) => v.stoppedContainers && v.stoppedContainers.length > 0,
+      ).length;
+      // Only show "in use" warning if containers weren't stopped
+      if (inUseCount > 0 && stoppedCount < inUseCount) {
+        const notStoppedCount = inUseCount - stoppedCount;
         summaryItems.push({
           label: "Volumes in use",
-          value: `${inUseCount} (data may be inconsistent)`,
+          value: `${notStoppedCount} (data may be inconsistent)`,
         });
       }
     }
@@ -254,6 +291,16 @@ ${color.dim("INLINE CONFIG OPTIONS:")}
       --no-docker                  Disable Docker volume backups
       --docker-volume <name>       Docker volume to backup (can be repeated)
 
+${color.dim("DOCKER CONTAINER OPTIONS:")}
+      --stop-containers            Stop containers using volumes before backup
+      --no-stop-containers         Keep containers running during backup (default)
+      --stop-timeout <seconds>     Graceful stop timeout (default: 30)
+      --restart-retries <n>        Restart retry attempts (default: 3)
+
+${color.dim("IMPORTANT:")} When using --stop-containers, be aware that containers with
+restart policy "always" or "unless-stopped" may auto-restart during backup.
+Consider using "restart: on-failure" for cleaner backups.
+
 ${color.dim("EXAMPLES:")}
   backitup backup                          # Interactive schedule selection
   backitup backup -s manual                # Manual backup (non-interactive)
@@ -268,5 +315,10 @@ ${color.dim("INLINE CONFIG EXAMPLES:")}
   backitup backup -s manual --source /data --local-path /backups
   backitup backup -s manual --source /app --s3-bucket my-backups --no-local
   backitup backup -s manual --source /db --retention-count 5 --retention-days 7
+
+${color.dim("DOCKER EXAMPLES:")}
+  backitup backup -s manual --docker-volume mydb --stop-containers
+  backitup backup -s manual --stop-containers --stop-timeout 60
+  backitup backup -s manual --docker-volume postgres_data --stop-containers --restart-retries 5
 `);
 }