feat: use docker entrypoint for flexible env var docker config

Using Docker ENTRYPOINT should allow for configuration of running
versitygw within Docker container similar to how the systemd
service is setup with environment variables.

This also adds the backends azure and plugin to the acceptable
backend options for both docker and systemd.

Fixes #1335

.github/workflows/docker-bats.yml

@@ -14,7 +14,6 @@ jobs:
         run: |
           cp tests/.env.docker.default tests/.env.docker
           cp tests/.secrets.default tests/.secrets
-          # see https://github.com/versity/versitygw/issues/1034
           docker build \
             --build-arg="GO_LIBRARY=go1.23.1.linux-amd64.tar.gz" \
             --build-arg="AWS_CLI=awscli-exe-linux-x86_64.zip" \

Dockerfile

@@ -23,13 +23,16 @@ RUN go build -ldflags "-X=main.Build=${BUILD} -X=main.BuildTime=${TIME} -X=main.
 
 FROM alpine:latest
 
-# These arguments can be overriden when building the image
+# These arguments can be overridden when building the image
 ARG IAM_DIR=/tmp/vgw
 ARG SETUP_DIR=/tmp/vgw
 
 RUN mkdir -p $IAM_DIR
 RUN mkdir -p $SETUP_DIR
 
-COPY --from=0 /app/cmd/versitygw/versitygw /app/versitygw
+COPY --from=0 /app/cmd/versitygw/versitygw /usr/local/bin/versitygw
 
-ENTRYPOINT [ "/app/versitygw" ]
+COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+
+ENTRYPOINT [ "/usr/local/bin/docker-entrypoint.sh" ]

README.md

@@ -70,6 +70,29 @@ versitygw [global options] command [command options] [arguments...]
 ```
 The [global options](https://github.com/versity/versitygw/wiki/Global-Options) are specified before the backend type and the backend options are specified after.
 
+### Run the gateway in Docker
+
+Use the published image like the native binary by passing CLI arguments:
+
+```bash
+docker run --rm versity/versitygw:latest --version
+```
+
+When no command arguments are supplied, the container looks for `VGW_BACKEND` and optional `VGW_BACKEND_ARG`/`VGW_BACKEND_ARGS` environment variables to determine which backend to start. Backend-specific configuration continues to come from the existing environment flags (for example `ROOT_ACCESS_KEY`, `VGW_PORT`, and others).
+
+```bash
+docker run --rm \
+  -e ROOT_ACCESS_KEY=testuser \
+  -e ROOT_SECRET_KEY=secret \
+  -e VGW_BACKEND=posix \
+  -e VGW_BACKEND_ARG=/data \
+  -p 10000:7070 \
+  -v $(pwd)/data:/data \
+  versity/versitygw:latest
+```
+
+If you need to pass additional CLI options, set `VGW_ARGS` with a space-delimited list, or continue passing arguments directly to `docker run`.
+
 ***
 
 #### Versity gives you clarity and control over your archival storage, so you can allocate more resources to your core mission.

cmd/versitygw/plugin.go

@@ -32,8 +32,9 @@ func pluginCommand() *cli.Command {
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:    "config",
-				Usage:   "location of the config file",
+				Usage:   "location of the plugin config file",
 				Aliases: []string{"c"},
+				EnvVars: []string{"VGW_PLUGIN_CONFIG"},
 			},
 		},
 	}

docker-entrypoint.sh

@@ -0,0 +1,51 @@
+#!/bin/sh
+set -e
+
+BIN="${VGW_BINARY:-/usr/local/bin/versitygw}"
+
+if [ ! -x "$BIN" ]; then
+    echo "Entrypoint error: versitygw binary not found at $BIN" >&2
+    exit 1
+fi
+
+# If arguments were provided, run them directly for backward compatibility.
+if [ "$#" -gt 0 ]; then
+    exec "$BIN" "$@"
+fi
+
+backend="${VGW_BACKEND:-}"
+if [ -z "$backend" ]; then
+    cat >&2 <<'EOF'
+No command arguments were provided and VGW_BACKEND is unset.
+Set VGW_BACKEND to one of: posix, scoutfs, s3, azure, plugin
+or pass explicit arguments to the container to run the versitygw command directly.
+EOF
+    exit 1
+fi
+
+case "$backend" in
+    posix|scoutfs|s3|azure|plugin)
+        ;;
+    *)
+        echo "VGW_BACKEND invalid backend (was '$backend')." >&2
+        exit 1
+        ;;
+esac
+
+set -- "$backend"
+
+if [ -n "${VGW_BACKEND_ARG:-}" ]; then
+    set -- "$@" "$VGW_BACKEND_ARG"
+fi
+
+if [ -n "${VGW_BACKEND_ARGS:-}" ]; then
+    # shellcheck disable=SC2086
+    set -- "$@" ${VGW_BACKEND_ARGS}
+fi
+
+if [ -n "${VGW_ARGS:-}" ]; then
+    # shellcheck disable=SC2086
+    set -- "$@" ${VGW_ARGS}
+fi
+
+exec "$BIN" "$@"

extra/example.conf

@@ -23,7 +23,8 @@
 # VersityGW Required Options #
 ##############################
 
-# VGW_BACKEND must be defined, and must be one of: posix, scoutfs, or s3
+# VGW_BACKEND must be defined, and must be one of: posix, scoutfs, s3, azure,
+# or plugin
 # This defines the backend that the VGW will use for data access.
 VGW_BACKEND=posix
 
@@ -480,3 +481,48 @@ ROOT_SECRET_ACCESS_KEY=
 #VGW_S3_DISABLE_CHECKSUM=false
 #VGW_S3_SSL_SKIP_VERIFY=false
 #VGW_S3_DEBUG=false
+
+########
+# azure #
+########
+
+# The azure backend allows the gateway to store objects in Azure Blob Storage.
+# Buckets created through the gateway map to blob containers within the
+# configured storage account. This backend is useful when existing workflows
+# expect an S3-compatible interface while data resides in Azure.
+
+# When the azure backend is selected, configure credentials with one of the
+# following approaches:
+# - Shared key: Define AZ_ACCOUNT_NAME with the storage account name and
+#   AZ_ACCESS_KEY with the corresponding account key.
+# - SAS token: Set AZ_SAS_TOKEN to an account or container scoped SAS token.
+#   Provide AZ_ENDPOINT if the token does not implicitly define the endpoint.
+# - Default Azure credentials: Leave AZ_ACCOUNT_NAME and AZ_ACCESS_KEY blank
+#   and configure the standard Azure identity environment variables supported
+#   by the DefaultAzureCredential chain (e.g. AZURE_CLIENT_ID, AZURE_TENANT_ID,
+#   AZURE_CLIENT_SECRET, managed identity, etc.).
+# Use AZ_ENDPOINT to override the service URL (for example when targeting
+# Azurite or a sovereign cloud). If unset, it defaults to
+# https://<account>.blob.core.windows.net/ when an account name is provided.
+#AZ_ACCOUNT_NAME=
+#AZ_ACCESS_KEY=
+#AZ_SAS_TOKEN=
+#AZ_ENDPOINT=
+
+##########
+# plugin #
+##########
+
+# The plugin backend loads a Go plugin shared object that exposes a variable
+# named "Backend" of type *plugins.BackendPlugin. The gateway uses the
+# exported constructor to create the backend implementation at runtime.
+
+# Set VGW_BACKEND_ARG to the absolute path of the compiled plugin (.so) file.
+# The path must be readable by the gateway service account and remain stable
+# across restarts.
+#VGW_BACKEND_ARG=/usr/lib/versitygw/plugins/example.so
+
+# Provide the plugin-specific configuration file path via VGW_PLUGIN_CONFIG.
+# The gateway automatically forwards this value to the plugin backend when it
+# starts up.
+#VGW_PLUGIN_CONFIG=/etc/versitygw.d/example-plugin.conf

extra/versitygw@.service

@@ -17,7 +17,7 @@ Group=root
 
 EnvironmentFile=/etc/versitygw.d/%i.conf
 
-ExecStart=/bin/bash -c 'if [[ ! ("${VGW_BACKEND}" == "posix" || "${VGW_BACKEND}" == "scoutfs" || "${VGW_BACKEND}" == "s3") ]]; then echo "VGW_BACKEND environment variable not set to one of posix, scoutfs, or s3"; exit 1; fi && exec /usr/bin/versitygw "$VGW_BACKEND" "$VGW_BACKEND_ARG"'
+ExecStart=/bin/bash -c 'if [[ ! ("${VGW_BACKEND}" == "posix" || "${VGW_BACKEND}" == "scoutfs" || "${VGW_BACKEND}" == "s3" || "${VGW_BACKEND}" == "azure" || "${VGW_BACKEND}" == "plugin") ]]; then echo "VGW_BACKEND environment variable ${VGW_BACKEND} not set to valid backend type"; exit 1; fi && exec /usr/bin/versitygw "$VGW_BACKEND" "$VGW_BACKEND_ARG"'
 
 # Let systemd restart this service always
 Restart=always