Merge pull request #1569 from versity/ben/docker

.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