From 7aa733ae9e7ef0ad66eb9f19fbe60a1d545101d5 Mon Sep 17 00:00:00 2001 From: Ben McClelland Date: Fri, 3 Oct 2025 09:06:40 -0700 Subject: [PATCH] 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 | 1 - Dockerfile | 9 ++++-- README.md | 23 ++++++++++++++ cmd/versitygw/plugin.go | 3 +- docker-entrypoint.sh | 51 +++++++++++++++++++++++++++++++ extra/example.conf | 48 ++++++++++++++++++++++++++++- extra/versitygw@.service | 2 +- 7 files changed, 130 insertions(+), 7 deletions(-) create mode 100644 docker-entrypoint.sh diff --git a/.github/workflows/docker-bats.yml b/.github/workflows/docker-bats.yml index 5a3ae3f..f3c721c 100644 --- a/.github/workflows/docker-bats.yml +++ b/.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" \ diff --git a/Dockerfile b/Dockerfile index 00a486f..ddbb3c7 100644 --- a/Dockerfile +++ b/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" ] diff --git a/README.md b/README.md index d210ede..a714ed6 100644 --- a/README.md +++ b/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. diff --git a/cmd/versitygw/plugin.go b/cmd/versitygw/plugin.go index 7e1f218..c864a66 100644 --- a/cmd/versitygw/plugin.go +++ b/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"}, }, }, } diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh new file mode 100644 index 0000000..3688a65 --- /dev/null +++ b/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" "$@" diff --git a/extra/example.conf b/extra/example.conf index d1fd0ed..50f8e0e 100644 --- a/extra/example.conf +++ b/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://.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 diff --git a/extra/versitygw@.service b/extra/versitygw@.service index d2947d3..6c0ffef 100644 --- a/extra/versitygw@.service +++ b/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