Skip to content

Commit 290899b

Browse files
neomantraneomantra
committed
Breakout BUILDING.md from README.md
Signed-off-by: Evan Wies <evan@neomantra.net>
1 parent e67ddeb commit 290899b

3 files changed

Lines changed: 249 additions & 237 deletions

File tree

‎BUILDING.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Building Custom Images
2+
3+
Table of Contents
4+
=================
5+
6+
* [Building (from source)](#building-from-source)
7+
* [Building (RPM based)](#building-rpm-based)
8+
* [Building (DEB based)](#building-deb-based)
9+
* [Building (APK based)](#building-apk-based)
10+
* [Building (Windows based)](#building-windows-based)
11+
12+
Building (from source)
13+
======================
14+
15+
This Docker image can be built and customized by cloning the repo and running `docker build` with the desired Dockerfile:
16+
17+
```
18+
git clone https://github.com/openresty/docker-openresty.git
19+
cd docker-openresty
20+
docker build -t myopenresty -f bionic/Dockerfile .
21+
docker run myopenresty
22+
```
23+
24+
Dockerfiles are provided for the following base systems, selecting the Dockerfile path with `-f`:
25+
26+
* [Alpine](https://github.com/openresty/docker-openresty/blob/master/alpine/Dockerfile) (`alpine/Dockerfile`)
27+
* [Alpine Fat](https://github.com/openresty/docker-openresty/blob/master/alpine/Dockerfile.fat) (`alpine/Dockerfile.fat`)
28+
* [Ubuntu Bionic](https://github.com/openresty/docker-openresty/blob/master/bionic/Dockerfile) (`bionic/Dockerfile`)
29+
* [Ubuntu Focal](https://github.com/openresty/docker-openresty/blob/master/focal/Dockerfile) (`focal/Dockerfile`)
30+
* [Ubuntu Jammy](https://github.com/openresty/docker-openresty/blob/master/jammy/Dockerfile) (`jammy/Dockerfile`)
31+
* [Ubuntu Noble](https://github.com/openresty/docker-openresty/blob/master/noble/Dockerfile) (`noble/Dockerfile`)
32+
33+
We used to support more build flavors but have trimmed that down. Older Dockerfiles are archived in the [`archive`](https://github.com/openresty/docker-openresty/tree/master/archive) folder.
34+
35+
36+
The following are the available build-time options. They can be set using the `--build-arg` CLI argument, like so:
37+
38+
```
39+
docker build --build-arg RESTY_J=4 -f jammy/Dockerfile .
40+
```
41+
42+
| Key | Default | Description |
43+
|:-----------------------------------------| :-----: |:----------- |
44+
| RESTY_IMAGE_BASE | "ubuntu" / "alpine" | The Debian or Alpine Docker image base to build `FROM`. |
45+
| RESTY_IMAGE_TAG | "noble" / "3.22.2" | The Debian or Alpine Docker image tag to build `FROM`. |
46+
| RESTY_VERSION | 1.27.1.2 | The version of OpenResty to use. |
47+
| RESTY_LUAROCKS_VERSION | 3.12.2 | The version of LuaRocks to use. |
48+
| RESTY_OPENSSL_VERSION | 3.4.3 | The version of OpenSSL to use. |
49+
| RESTY_OPENSSL_PATCH_VERSION | 3.4.1 | The version of OpenSSL to use when patching. |
50+
| RESTY_OPENSSL_URL_BASE | "https://github.com/openssl/openssl/releases/download/openssl-${RESTY_OPENSSL_VERSION}" | The base of the URL to download OpenSSL from. |
51+
| RESTY_OPENSSL_BUILD_OPTIONS | "enable-camellia enable-seed enable-rfc3779 enable-cms enable-md2 enable-rc5 enable-weak-ssl-ciphers enable-ssl3 enable-ssl3-method enable-md2 enable-ktls enable-fips" | Options to tweak Resty's OpenSSL build. |
52+
| RESTY_PCRE_VERSION | 10.44 | The version of PCRE2 to use. |
53+
| RESTY_PCRE_SHA256 | `86b9cb0aa3bcb7994faa88018292bc704cdbb708e785f7c74352ff6ea7d3175b` | The SHA-256 checksum of the PCRE2 package to check. |
54+
| RESTY_PCRE_BUILD_OPTIONS | "--enable-jit --enable-pcre2grep-jit --disable-bsr-anycrlf --disable-coverage --disable-ebcdic --disable-fuzz-support \
55+
--disable-jit-sealloc --disable-never-backslash-C --enable-newline-is-lf --enable-pcre2-8 --enable-pcre2-16 --enable-pcre2-32 \
56+
--enable-pcre2grep-callout --enable-pcre2grep-callout-fork --disable-pcre2grep-libbz2 --disable-pcre2grep-libz --disable-pcre2test-libedit \
57+
--enable-percent-zt --disable-rebuild-chartables --enable-shared --disable-static --disable-silent-rules --enable-unicode --disable-valgrind" | Options to tweak Resty's PCRE build. |
58+
| RESTY_PCRE_OPTIONS | "--with-pcre-jit" | Options to tweak Resty's build args regarding PCRE. |
59+
| RESTY_J | 1 | Sets the parallelism level (-jN) for the builds. |
60+
| RESTY_CONFIG_OPTIONS | "--with-compat --without-http_rds_json_module --without-http_rds_csv_module --without-lua_rds_parser --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module --with-http_addition_module --with-http_auth_request_module --with-http_dav_module --with-http_flv_module --with-http_geoip_module=dynamic --with-http_gunzip_module --with-http_gzip_static_module --with-http_image_filter_module=dynamic --with-http_mp4_module --with-http_random_index_module --with-http_realip_module --with-http_secure_link_module --with-http_slice_module --with-http_ssl_module --with-http_stub_status_module --with-http_sub_module --with-http_v2_module --with-http_v3_module --with-http_xslt_module=dynamic --with-ipv6 --with-mail --with-mail_ssl_module --with-md5-asm --with-sha1-asm --with-stream --with-stream_ssl_module --with-stream_ssl_preread_module --with-threads" | Options to pass to OpenResty's `./configure` script. |
61+
| RESTY_LUAJIT_OPTIONS | "--with-luajit-xcflags='-DLUAJIT_NUMMODE=2 -DLUAJIT_ENABLE_LUA52COMPAT'" | Options to tweak LuaJIT. |
62+
| RESTY_CONFIG_OPTIONS_MORE | "" | More options to pass to OpenResty's `./configure` script. |
63+
| RESTY_ADD_PACKAGE_BUILDDEPS | "" | Additional packages to install with package manager required by build only (removed after installation) |
64+
| RESTY_ADD_PACKAGE_RUNDEPS | "" | Additional packages to install with package manager required at runtime (not removed after installation) |
65+
| RESTY_EVAL_PRE_CONFIGURE | "" | Command(s) to run prior to executing OpenResty's `./configure` script. (this can be used to clone a github repo of an extension you want to add to OpenResty, for example. In that case, dont forget to add the appropriate argument to the RESTY_CONFIG_OPTIONS_MORE argument as described above). |
66+
| RESTY_EVAL_POST_DOWNLOAD_PRE_CONFIGURE | "" | Command(s) to run after downloading and extracting OpenResty's source tarball, but prior to executing OpenResty's `./configure` script. Working directory will be the extracted OpenResty source directory. |
67+
| RESTY_EVAL_PRE_MAKE | "" | Command(s) to run before running `make install`. |
68+
| RESTY_EVAL_POST_MAKE | "" | Command(s) to run after running `make install`. |
69+
| RESTY_STRIP_BINARIES | "" | Set to non-zero to strip binaries in Alpine images. |
70+
These built-from-source flavors include the following modules by default, but one can easily increase or decrease that with the custom build options above:
71+
72+
* http_addition_module
73+
* http_auth_request_module
74+
* http_dav_module
75+
* http_flv_module
76+
* http_geoip_module=dynamic
77+
* http_gunzip_module
78+
* http_gzip_static_module
79+
* http_image_filter_module=dynamic
80+
* http_mp4_module
81+
* http_random_index_module
82+
* http_realip_module
83+
* http_secure_link_module
84+
* http_slice_module
85+
* http_ssl_module
86+
* http_stub_status_module
87+
* http_sub_module
88+
* http_v2_module
89+
* http_v3_module
90+
* http_xslt_module=dynamic
91+
* ipv6
92+
* mail
93+
* mail_ssl_module
94+
* md5-asm
95+
* pcre-jit
96+
* sha1-asm
97+
* stream
98+
* stream_ssl_module
99+
* stream_ssl_preread_module
100+
* threads
101+
102+
[Back to TOC](#table-of-contents)
103+
104+
105+
Building (RPM based)
106+
====================
107+
108+
OpenResty now now has [RPMs available](https://openresty.org/en/rpm-packages.html). The `centos` and `fedora` images use these RPMs rather than building from source.
109+
110+
This Docker image can be built and customized by cloning the repo and running `docker build` with the desired Dockerfile:
111+
112+
* [CentOS 7 RPM](https://github.com/openresty/docker-openresty/blob/master/centos7/Dockerfile) (`centos/Dockerfile`)
113+
* [CentOS 8 RPM](https://github.com/openresty/docker-openresty/blob/master/centos/Dockerfile) (`centos/Dockerfile`)
114+
* [Fedora 35 RPM](https://github.com/openresty/docker-openresty/blob/master/fedora/Dockerfile) (`centos/Dockerfile`)
115+
116+
The following are the available build-time options. They can be set using the `--build-arg` CLI argument, like so:
117+
118+
```
119+
docker build --build-arg RESTY_RPM_FLAVOR="-debug" centos7/Dockerfile .
120+
docker build --build-arg RESTY_RPM_FLAVOR="-debug" centos/Dockerfile .
121+
docker build --build-arg RESTY_RPM_FLAVOR="-debug" -f fedora/Dockerfile .
122+
```
123+
124+
| Key | Default | Description |
125+
|:----- | :-----: |:----------- |
126+
|RESTY_IMAGE_BASE | "centos" | The Centos Docker image base to build `FROM`. |
127+
|RESTY_IMAGE_TAG | "8" | The CentOS Docker image tag to build `FROM`. |
128+
|RESTY_LUAROCKS_VERSION | 3.12.2 | The version of LuaRocks to use. |
129+
|RESTY_YUM_REPO | "https://openresty.org/package/centos/openresty.repo" | URL for the OpenResty YUM Repository. |
130+
|RESTY_RPM_FLAVOR | "" | The `openresty` package flavor to use. Possibly `"-debug"` or `"-valgrind"`. |
131+
|RESTY_RPM_VERSION | "1.27.1.2-1" | The `openresty` package version to install. |
132+
|RESTY_RPM_DIST | "el8" | The `openresty` package distribution to install. |
133+
|RESTY_RPM_ARCH | "x86_64" | The `openresty` package architecture to install. |
134+
135+
[Back to TOC](#table-of-contents)
136+
137+
138+
Building (DEB based)
139+
====================
140+
141+
OpenResty now now has [Debian Packages (DEBs) available](https://openresty.org/en/deb-packages.html). The `bullseye` image use these DEBs rather than building from source.
142+
143+
You can derive your own Docker images from this to install your own packages. See [bookworm/Dockerfile.fat](https://github.com/openresty/docker-openresty/blob/master/bookworm/Dockerfile.fat) and [buster/Dockerfile.luarocks_example](https://github.com/openresty/docker-openresty/blob/master/archive/buster/Dockerfile.luarocks_example).
144+
145+
This Docker image can be built and customized by cloning the repo and running `docker build` with the desired Dockerfile:
146+
147+
* [Debian Bookworm 12 DEB](https://github.com/openresty/docker-openresty/blob/master/bookworm/Dockerfile) (`bookworm/Dockerfile`)
148+
* [Debian Bullseye 11 DEB](https://github.com/openresty/docker-openresty/blob/master/bullseye/Dockerfile) (`bullseye/Dockerfile`)
149+
150+
The following are the available build-time options. They can be set using the `--build-arg` CLI argument, like so:
151+
152+
```
153+
docker build --build-arg RESTY_DEB_FLAVOR="-debug" -f bullseye/Dockerfile .
154+
```
155+
156+
| Key | Default | Description |
157+
:----- | :-----: |:----------- |
158+
|RESTY_APT_REPO | "https://openresty.org/package/debian" | Apt repo to load from. |
159+
|RESTY_APT_PGP | "https://openresty.org/package/pubkey.gpg" | URL to download APT PGP key from |
160+
|RESTY_APT_ARCH | `amd64` | Architecture for APT lookups |
161+
|RESTY_IMAGE_BASE | "debian" | The Debian Docker image base to build `FROM`. |
162+
|RESTY_IMAGE_TAG | "bullseye-slim" | The Debian Docker image tag to build `FROM`. |
163+
|RESTY_DEB_FLAVOR | "" | The `openresty` package flavor to use. Possibly `"-debug"` or `"-valgrind"`. |
164+
|RESTY_DEB_VERSION | "=1.27.1.2-1~bookworm1" | The [Debian package version](https://openresty.org/package/debian/pool/openresty/o/openresty/) to use, with `=` prepended. |
165+
|RESTY_FAT_DEB_FLAVOR | "" | The `openresty` package flavor to use to install "fat" packages. Possibly `"-debug"` or `"-valgrind"`. |
166+
|RESTY_FAT_DEB_VERSION | "=1.27.1.2-1~bookworm1" | The [Debian package version](https://openresty.org/package/debian/pool/openresty/o/openresty/) to use to "fat" packages, with `=` prepended. |
167+
168+
* For `amd64` builds, `RESTY_APT_REPO="https://openresty.org/package/debian"`
169+
* For `arm64` builds, `RESTY_APT_REPO="https://openresty.org/package/arm64/debian"`
170+
171+
[Back to TOC](#table-of-contents)
172+
173+
174+
Building (APK based)
175+
====================
176+
177+
OpenResty now now has [Alpine Packagesx-5q (APKs) available](https://openresty.org/en/apk-packages.html). The `alpine-apk` image use these APKs rather than building from source. You can derive your own Docker images from this to install your own packages.
178+
179+
This Docker image can be built and customized by cloning the repo and running `docker build` with the desired Dockerfile:
180+
181+
* [Alpine APK](https://github.com/openresty/docker-openresty/blob/master/alpine-apk/Dockerfile) (`alpine-apk/Dockerfile`)
182+
183+
The following are the available build-time options. They can be set using the `--build-arg` CLI argument, like so:
184+
185+
```
186+
docker build --build-arg RESTY_IMAGE_TAG="3.12" -f alpine-apk/Dockerfile .
187+
```
188+
189+
| Key | Default | Description |
190+
|:----- | :-----: |:----------- |
191+
|RESTY_IMAGE_BASE | "alpine" | The Alpine Docker image base to build `FROM`. |
192+
|RESTY_IMAGE_TAG | "3.18.12" | The Alpine Docker image tag to build `FROM`. |
193+
|RESTY_APK_ALPINE_VERSION | "3.18" | The Alpine version for RESTY_APK_REPO_URL. |
194+
|RESTY_APK_KEY_URL | "https://openresty.org/package/admin@openresty.com-5ea678a6.rsa.pub" | The URL of the signing key of the `openresty` package. |
195+
|RESTY_APK_REPO_URL | "https://openresty.org/package/alpine/v${RESTY_APK_ALPINE_VERSION}/main" | The URL of the APK repository for `openresty` package. |
196+
|RESTY_APK_VERSION | "=1.27.1.2-r0" | The suffix to add to the apk install package name: `openresty${RESTY_APK_VERSION`}. |
197+
198+
[Back to TOC](#table-of-contents)
199+
200+
201+
Building (Windows based)
202+
========================
203+
204+
This Docker image can be built and customized by cloning the repo and running `docker build` with the desired Dockerfile:
205+
206+
* [Windows](https://github.com/openresty/docker-openresty/blob/master/centos-rpm/Dockerfile) (`windows/Dockerfile`)
207+
208+
The following are the available build-time options. They can be set using the `--build-arg` CLI argument, like so:
209+
210+
```
211+
docker build --build-arg RESTY_VERSION="1.27.1.2" -f windows/Dockerfile .
212+
```
213+
214+
| Key | Default | Description |
215+
|:----- | :-----: |:----------- |
216+
|RESTY_INSTALL_BASE | "mcr.microsoft.com/dotnet/framework/runtime" | The Windows Server Docker image name to download and install OpenResty with. |
217+
|RESTY_INSTALL_TAG | "4.8-windowsservercore-ltsc2019" | The Windows Server Docker image name to download and install OpenResty with. |
218+
|RESTY_IMAGE_BASE | "mcr.microsoft.com/windows/nanoserver" | The Windows Server Docker image name to build `FROM` for final image. |
219+
|RESTY_IMAGE_TAG | "1809" | The Windows Server Docker image tag to build `FROM` for final image. |
220+
|RESTY_VERSION | 1.27.1.2 | The version of OpenResty to use. |
221+
222+
[Back to TOC](#table-of-contents)

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
## 1.27.1.2-6 (2025-11-08)
55

66
* Install `-dev` libraries in `bookworm-buildpack` flavor ([#283](https://github.com/openresty/docker-openresty/issues/283))
7+
* Extracted custom image build documentation to [`BUILDING.md`](./BUILDING.md)
78

89
## 1.27.1.2-5 (2025-10-30)
910

0 commit comments

Comments
 (0)