nginxinc/nginx-s3-gateway
Authenticating and caching gateway based on NGINX for S3 API back-ends.
5M+
This project provides a working configuration of NGINX configured to act as an authenticating and caching gateway for to AWS S3 or another S3 compatible service. This allows you to proxy a private S3 bucket without requiring users to authenticate to it. Within the proxy layer, additional functionality can be configured such as:
All such functionality can be enabled within a standard NGINX configuration because this project is nothing other than NGINX with additional configuration that allows for proxying S3. It can be used as-is if the predefined configuration is sufficient, or it can serve as a base example for a more customized configuration.
If the predefined configuration does not meet your needs, it is best to borrow from the patterns in this project and build your own configuration. For example, if you want to enable SSL/TLS and compression in your NGINX S3 gateway configuration, you will need to look at other documentation because this project does not enable those features of NGINX.
This project can be run as a stand-alone container or as a Systemd service. Both modes use the same NGINX configuration and are functionally equal in terms features. However, in the case of running as a Systemd service, other services can be configured that additional functionality such as certbot for Let's Encrypt support.
Refer to the Getting Started Guide for how to build and run the gateway.
The following environment variables are used to configure the gateway when running as a Container or as a Systemd service.
ALLOW_DIRECTORY_LIST
- Enable directory listing - either true or falseAWS_SIGS_VERSION
- AWS Signatures API version - either 2 or 4DNS_RESOLVERS
- (optional) DNS resolvers (separated by single spaces) to configure NGINX withS3_ACCESS_KEY_ID
- Access keyS3_BUCKET_NAME
- Name of S3 bucket to proxy requests toS3_DEBUG
- Flag (true/false) enabling AWS signatures debug output (default: false)S3_REGION
- Region associated with APIS3_SECRET_KEY
- Secret access keyS3_SERVER_PORT
- SSL/TLS port to connect toS3_SERVER_PROTO
- Protocol to used connect to S3 server - http
or https
S3_SERVER
- S3 host to connect toS3_STYLE
- The S3 host/path method - virtual
, path
or default
. virtual
is
the method that that uses DNS-style bucket+hostname:port.
This is the default
value. path
is a method that appends the bucket name
as the first directory in the URI's path. This method is used by many S3
compatible services. See this
AWS blog article
for further information.PROXY_CACHE_VALID_OK
- Sets caching time for response code 200 and 302PROXY_CACHE_VALID_NOTFOUND
- Sets caching time for response code 404PROXY_CACHE_VALID_FORBIDDEN
- Sets caching time for response code 403If you are using AWS instance profile credentials,
you will need to omit the S3_ACCESS_KEY_ID
and S3_SECRET_KEY
variables from
the configuration.
When running with Docker, the above environment variables can be set in a file
with the --env-file
flag. When running as a Systemd service, the environment
variables are specified in the /etc/nginx/environment
file. An example of
the format of the file can be found in the settings.example
file.
Refer to the Development Guide for more information about extending or testing the gateway.
All code include is licensed under the Apache 2.0 license.
docker pull nginxinc/nginx-s3-gateway