Add "print-config" subcommand (#698)

* Add "show-config" subcommand

* Add integration tests

* Handle wrong additional args

* Support "BackupFilenameExpand" option

* Rename to print-config

* Remove config nil check as it will never be nil

* Rework print config to work with config.resolve()

* Use defer unset()

* Add warning about feature not being stable yet

cmd/backup/main.go

@@ -11,8 +11,18 @@ func main() {
 	foreground := flag.Bool("foreground", false, "run the tool in the foreground")
 	profile := flag.String("profile", "", "collect runtime metrics and log them periodically on the given cron expression")
 	flag.Parse()
-
+	additionalArgs := flag.Args()
 	c := newCommand()
+
+	if len(additionalArgs) > 0 {
+		switch additionalArgs[0] {
+		case "print-config":
+			c.must(runPrintConfig())
+			return
+		default:
+			panic("unknown command: " + additionalArgs[0])
+		}
+	}
 	if *foreground {
 		opts := foregroundOpts{
 			profileCronExpression: *profile,

cmd/backup/print_config.go

@@ -0,0 +1,47 @@
+// Copyright 2025 - offen.software <hioffen@posteo.de>
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"regexp"
+
+	"github.com/offen/docker-volume-backup/internal/errwrap"
+)
+
+func runPrintConfig() error {
+	configurations, err := sourceConfiguration(configStrategyConfd)
+	if err != nil {
+		return errwrap.Wrap(err, "error sourcing configuration")
+	}
+
+	formatter := regexp.MustCompile(`\s([A-Z])`)
+	for _, config := range configurations {
+		if err := func() (err error) {
+			unset, warnings, err := config.resolve()
+			if err != nil {
+				return errwrap.Wrap(err, "error resolving configuration")
+			}
+			defer func() {
+				if derr := unset(); derr != nil {
+					err = errors.Join(err, errwrap.Wrap(derr, "error unsetting environment variables"))
+				}
+			}()
+
+			fmt.Printf("source=%s\n", config.source)
+			for _, warning := range warnings {
+				fmt.Printf("warning:%s\n", warning)
+			}
+			// insert line breaks before each field name, assuming field names start with uppercase letters
+			formatted := formatter.ReplaceAllString(fmt.Sprintf("%+v", *config), "\n$1")
+			fmt.Printf("%s\n", formatted)
+			return nil
+		}(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

docs/how-tos/print-configuration.md

@@ -0,0 +1,27 @@
+---
+title: Show loaded configuration
+layout: default
+parent: How Tos
+nav_order: 8
+---
+
+# Print loaded configuration
+
+You can print the configuration that `docker-volume-backup` has picked up without running a backup:
+
+```console
+docker exec <container_ref> backup print-config
+```
+
+If configuration sourcing fails, the error is printed to stdout to aid debugging.
+
+If you want to test a one-off value, pass it directly:
+
+```console
+docker exec -e BACKUP_SOURCES=/backup -e NOTIFICATION_URLS=stdout:// <container_ref> backup print-config
+```
+{: .note }
+Output includes secrets exactly as loaded.
+
+{: .warning }
+This feature is still in development and might change in future releases.

docs/reference/index.md

@@ -19,6 +19,7 @@ You can work around this by either updating `docker-compose` or unquoting your c
 
 You can populate below template according to your requirements and use it as your `env_file`.
 The values for each key currently match its default.
+If you need to confirm what the container actually loaded, see [Show loaded configuration](../how-tos/print-configuration.md).
 
 {% raw %}
 ```

test/print-config/conf.d/01print-config.env

@@ -0,0 +1,2 @@
+BACKUP_SOURCES=/conf-backup
+NOTIFICATION_URLS_FILE=/run/secrets/notification_urls

test/print-config/docker-compose.confd.yml

@@ -0,0 +1,6 @@
+services:
+  backup:
+    image: offen/docker-volume-backup:${TEST_VERSION:-canary}
+    volumes:
+      - ${CONF_DIR}:/etc/dockervolumebackup/conf.d:ro
+      - ${SECRET_FILE}:/run/secrets/notification_urls:ro

test/print-config/docker-compose.yml

@@ -0,0 +1,10 @@
+services:
+  backup:
+    image: offen/docker-volume-backup:${TEST_VERSION:-canary}
+    environment:
+      BACKUP_FILENAME: "backup-$${BACKUP_TAG}.tar"
+      BACKUP_FILENAME_EXPAND: true
+      BACKUP_TAG: expanded
+      BACKUP_SOURCES: /backup
+      NOTIFICATION_URLS: "stdout://"
+      AWS_S3_BUCKET_NAME: example-bucket

test/print-config/run.sh

@@ -0,0 +1,68 @@
+#!/bin/sh
+
+set -e
+
+cd "$(dirname "$0")"
+. ../util.sh
+current_test=$(basename $(pwd))
+
+info "print-config with environment variables"
+docker compose up -d --quiet-pull
+logs=$(docker compose exec -T backup backup print-config)
+
+echo "$logs"
+
+if ! echo "$logs" | grep -q "source=from environment"; then
+  fail "Missing source line."
+fi
+pass "Source line present."
+
+if ! echo "$logs" | grep -q "BackupSources:/backup"; then
+  fail "Missing BACKUP_SOURCES in output."
+fi
+pass "BACKUP_SOURCES present."
+
+if ! echo "$logs" | grep -q "BackupFilename:backup-expanded.tar"; then
+  fail "Missing expanded BACKUP_FILENAME in output."
+fi
+pass "Expanded BACKUP_FILENAME present."
+
+if ! echo "$logs" | grep -q "NotificationURLs:\[stdout://\]"; then
+  fail "Missing NOTIFICATION_URLS in output."
+fi
+pass "NOTIFICATION_URLS present."
+
+if ! echo "$logs" | grep -q "AwsS3BucketName:example-bucket"; then
+  fail "Missing AWS_S3_BUCKET_NAME in output."
+fi
+pass "AWS_S3_BUCKET_NAME present."
+
+docker compose down
+
+info "print-config with conf.d and _FILE"
+export CONF_DIR=$(pwd)/conf.d
+export SECRET_FILE=$(mktemp)
+printf "stdout://\n" > "$SECRET_FILE"
+
+docker compose -f docker-compose.confd.yml up -d --quiet-pull
+logs=$(docker compose -f docker-compose.confd.yml exec -T backup backup print-config)
+
+echo "$logs"
+
+if ! echo "$logs" | grep -q "source=01print-config.env"; then
+  fail "Missing conf.d source line."
+fi
+pass "conf.d source line present."
+
+if ! echo "$logs" | grep -q "BackupSources:/conf-backup"; then
+  fail "Missing conf.d BACKUP_SOURCES in output."
+fi
+pass "conf.d BACKUP_SOURCES present."
+
+if ! echo "$logs" | grep -q "NotificationURLs:\\[stdout://"; then
+  fail "Missing conf.d NOTIFICATION_URLS in output."
+fi
+pass "conf.d NOTIFICATION_URLS present."
+
+docker compose -f docker-compose.confd.yml down
+rm -f "$SECRET_FILE"