It's possible to extend a mainline image with third-party modules either from
your own instructions following a simple filesystem layout/syntax using
build_module.sh
helper script, or falling back to package sources from
pkg-oss.
To use the Dockerfiles provided here,
Docker BuildKit is required.
This is enabled by default as of version 23.0; for earlier versions this can be
enabled by setting the environment variable DOCKER_BUILDKIT
to 1
.
If you can not or do not want to use BuildKit, you can use a previous version of these files, see for example https://github.com/nginxinc/docker-nginx/tree/4bf0763f4977fff7e9648add59e0540088f3ca9f/modules.
$ docker build --build-arg ENABLED_MODULES="ndk lua" -t my-nginx-with-lua .
This command will attempt to build an image called my-nginx-with-lua
based on
official nginx docker hub image with two modules: ndk
and lua
.
By default, a Debian-based image will be used. If you wish to use Alpine
instead, add -f Dockerfile.alpine
to the command line. By default, mainline
images are used as a base, but it's possible to specify a different image by
providing NGINX_FROM_IMAGE
build argument, e.g. --build-arg NGINX_FROM_IMAGE=nginx:stable
.
The build script will look for module build definition files on filesystem directory under the same name as the module (and resulting package) and if those are not found will try to look up requested modules in the pkg-oss repository.
For well-known modules we maintain a set of build sources packages over at
pkg-oss
, so it's probably a good idea to rely on those instead of providing
your own implementation.
As of the time of writing this README, the following modules and their versions
are available from pkg-oss
repository:
/pkg-oss $ LC_ALL=C make -C debian list-all-modules
auth-spnego 1.1.1-1
brotli 1.0.0-1
encrypted-session 0.09-1
fips-check 0.1-1
geoip 1.25.5-1
geoip2 3.4-1
headers-more 0.35-1
image-filter 1.25.5-1
lua 0.10.26-1
ndk 0.3.3-1
njs 0.8.4-2
opentracing 0.33.0-1
otel 0.1.0-1
passenger 6.0.19-1
perl 1.25.5-1
rtmp 1.2.2-1
set-misc 0.33-1
subs-filter 0.6.4-1
xslt 1.25.5-1
If you still want to provide your own instructions for a specific module,
organize the build directory in a following way, e.g. for echo
module:
docker-nginx/modules $ tree echo
echo
├── build-deps
├── prebuild
└── source
0 directories, 3 files
The scripts expect one file to always exist for a module you wish to build
manually: source
. It should contain a link to a zip/tarball source code of a
module you want to build. In build-deps
you can specify build dependencies
for a module as found in Debian or Alpine repositories. prebuild
is a shell
script (make it chmod +x prebuild
!) that will be executed prior to building
the module but after installing the dependencies, so it can be used to install
additional build dependencies if they are not available from Debian or Alpine.
Keep in mind that those dependencies wont be automatically copied to the
resulting image and if you're building a library, build it statically.
Once the build is done in the builder image, the built packages are copied over to resulting image and installed via apt/apk. The resulting image will be tagged and can be used the same way as an official docker hub image.
Note that we can not provide any support for those modifications and in no way guarantee they will work as nice as a build without third-party modules. If you encounter any issues running your image with the modules enabled, please reproduce with a vanilla image first.
If desired modules are already packaged in
pkg-oss - e.g. debian/Makefile.module-*
exists for a given module, you can use this example.
- Create a directory for your project:
mkdir myapp
cd myapp
- Populate the build context for a custom nginx image:
mkdir my-nginx
curl -o my-nginx/Dockerfile https://raw.githubusercontent.com/nginxinc/docker-nginx/master/modules/Dockerfile
- Create a
docker-compose.yml
file:
cat > docker-compose.yml << __EOF__
version: "3.3"
services:
web:
build:
context: ./my-nginx/
args:
ENABLED_MODULES: ndk lua
image: my-nginx-with-lua:v1
ports:
- "80:8000"
__EOF__
Now, running docker-compose up --build -d
will build the image and run the application for you.
If a needed module is not available via pkg-oss
, you can use this example.
We're going to build the image with ngx_cache_purge module.
The steps are similar to a previous example, with a notable difference of providing a URL to fetch the module source code from.
- Create a directory for your project:
mkdir myapp-cache
cd myapp-cache
- Populate the build context for a custom nginx image:
mkdir my-nginx
curl -o my-nginx/Dockerfile https://raw.githubusercontent.com/nginxinc/docker-nginx/master/modules/Dockerfile
mkdir my-nginx/cachepurge
echo "https://github.com/FRiCKLE/ngx_cache_purge/archive/2.3.tar.gz" > my-nginx/cachepurge/source
- Create a
docker-compose.yml
file:
cat > docker-compose.yml << __EOF__
version: "3.3"
services:
web:
build:
context: ./my-nginx/
args:
ENABLED_MODULES: cachepurge
image: my-nginx-with-cachepurge:v1
ports:
- "80:8080"
__EOF__
Now, running docker-compose up --build -d
will build the image and run the application for you.