Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 401 Commits
.github		.github
common		common
deployments		deployments
docs		docs
examples		examples
jsdoc		jsdoc
oss/etc/nginx		oss/etc/nginx
plus		plus
test		test
.gitignore		.gitignore
.tool-versions		.tool-versions
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile.buildkit.plus		Dockerfile.buildkit.plus
Dockerfile.latest-njs		Dockerfile.latest-njs
Dockerfile.oss		Dockerfile.oss
Dockerfile.plus		Dockerfile.plus
Dockerfile.unprivileged		Dockerfile.unprivileged
GNUmakefile		GNUmakefile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
package-lock.json		package-lock.json
package.json		package.json
settings.example		settings.example
standalone_ubuntu_oss_install.sh		standalone_ubuntu_oss_install.sh
test.sh		test.sh

Repository files navigation

NGINX S3 Gateway

Introduction

This project provides a working configuration of NGINX configured to act asan authenticating and caching gateway for to AWS S3 or another S3 compatibleservice. This allows you to proxy a private S3 bucket without requiring usersto authenticate to it. Within the proxy layer, additional functionality can beconfigured such as:

Listing the contents of a S3 bucket
Providing an authentication gateway using an alternative authenticationsystem to S3
Caching frequently accessed S3 objects for lower latency delivery andprotection against S3 outages
For internal/micro services that can't authenticate against the S3 API(e.g. don't have libraries available) the gateway can provide a meansto accessing S3 objects without authentication
Compressing objects (gzip,brotli) from gateway to end user
Protecting S3 bucket from arbitrary public access and traversal
Rate limiting S3 objects
Protecting a S3 bucket with aWAF
Serving static assets from a S3 bucket alongside a dynamic applicationendpoints all in a single RESTful directory structure

All such functionality can be enabled within a standard NGINX configurationbecause this project is nothing other than NGINX with additional configurationthat allows for proxying S3. It can be used as-is if the predefinedconfiguration is sufficient, or it can serve as a base example for a morecustomized configuration.

If the predefined configuration does not meet your needs, it is best to borrowfrom 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 gatewayconfiguration, you will need to look at other documentation because thisproject does not enable those features of NGINX.

Usage

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 termsfeatures. However, in the case of running as a Systemd service, other servicescan be configured that additional functionality such ascertbotforLet's Encrypt support.

Getting Started

Refer to theGetting Started Guide for how to buildand run the gateway.

Directory Structure and File Descriptions

common/                          contains files used by both NGINX OSS and Plus configurations  etc/nginx/include/    awscredentials.js            common library to read and write credentials    awssig2.js                   common library to build AWS signature 2    awssig4.js                   common library to build AWS signature 4 and get a session token    s3gateway.js                 common library to integrate the s3 storage from NGINX OSS and Plus    utils.js                     common library to be reused by all of NJS codebasesdeployments/                     contains files used for deployment technologies such as                                 CloudFormationdocs/                            contains documentation about the projectexamples/                        contains additional `Dockerfile` examples that extend the base                                 configurationjsdoc                            JSDoc configuration filesoss/                             contains files used solely in NGINX OSS configurationsplus/                            contains files used solely in NGINX Plus configurationstest/                            contains automated tests for validang that the examples workDockerfile.oss                   Dockerfile that configures NGINX OSS to act as a S3 gatewayDockerfile.plus                  Dockerfile that builds a NGINX Plus instance that is configured                                 equivelently to NGINX OSS - instance is configured to act as a                                 S3 gateway with NGINX Plus additional features enabledDockerfile.buildkit.plus         Dockerfile with the same configuration as Dockerfile.plus, but                                 with support for hiding secrets using Docker's BuildkitDockerfile.latest-njs            Dockerfile that inherits from the last build of the gateway and                                 then builds and installs the latest version of njs from sourceDockerfile.unprivileged          Dockerfiles that inherits from the last build of the gateway and                                 makes the necessary modifications to allow running the container                                 as a non root, unprivileged user.package.json                     Node.js package file used only for generating JSDocsettings.example                 Docker env file examplestandalone_ubuntu_oss_install.sh install script that will install the gateway as a Systemd servicetest.sh                          test launcher