Skip to content

Commit ad8684c

Browse files
committed
docs: fix port mapping documentation for unprivileged containers
Resolves #428 Add dedicated section explaining that unprivileged container images listen on port 8080 internally (not port 80), as they run as non-root users and cannot bind to privileged ports. Changes: - Add "Running Unprivileged Container Images" subsection with correct port mapping examples (80:8080 or 8080:8080) - Add note in Kubernetes section about containerPort for unprivileged images - Clarify security benefits of unprivileged containers The standard OSS images continue to use port 80 as they run as root. Only images tagged with 'unprivileged-oss-*' use port 8080.
1 parent 4af1807 commit ad8684c

File tree

1 file changed

+21
-2
lines changed

1 file changed

+21
-2
lines changed

docs/getting_started.md

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ sudo env $(cat settings.example) ./standalone_ubuntu_oss_install.sh
207207

208208
### Running the Public Open Source NGINX Container Image
209209

210-
The latest builds of the gateway (that use open source NGINX) are available on
210+
The latest builds of the gateway (that use open source NGINX) are available on
211211
the project's Github [package repository](https://github.com/nginxinc/nginx-s3-gateway/pkgs/container/nginx-s3-gateway%2Fnginx-oss-s3-gateway).
212212

213213
To run with the public open source image, replace the `settings` file specified
@@ -220,7 +220,7 @@ docker run --env-file ./settings --publish 80:80 --name nginx-s3-gateway \
220220
If you would like to run with the latest njs version, run:
221221
```
222222
docker run --env-file ./settings --publish 80:80 --name nginx-s3-gateway \
223-
ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:latest-njs-oss
223+
ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:latest-njs-oss
224224
```
225225

226226
Alternatively, if you would like to pin your version to a specific point in
@@ -230,6 +230,22 @@ docker run --env-file ./settings --publish 80:80 --name nginx-s3-gateway \
230230
ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:latest-njs-oss-20220310
231231
```
232232

233+
#### Running Unprivileged Container Images
234+
235+
Unprivileged container images run NGINX as a non-root user and listen on port **8080** internally (instead of port 80). This provides enhanced security by not requiring privileged ports.
236+
237+
To run an unprivileged image, use the `unprivileged-oss` tag and map to port **8080**:
238+
```
239+
docker run --env-file ./settings --publish 80:8080 --name nginx-s3-gateway \
240+
ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:unprivileged-oss-20250718
241+
```
242+
243+
Alternatively, you can map host port 8080 to container port 8080 to avoid requiring elevated privileges on the host:
244+
```
245+
docker run --env-file ./settings --publish 8080:8080 --name nginx-s3-gateway \
246+
ghcr.io/nginxinc/nginx-s3-gateway/nginx-oss-s3-gateway:unprivileged-oss-20250718
247+
```
248+
233249
### Building the Public Open Source NGINX Container Image
234250

235251
In order to build the NGINX OSS container image, do a `docker build` as follows
@@ -457,6 +473,9 @@ spec:
457473
path: /health
458474
port: http
459475
```
476+
477+
**Note:** If using an unprivileged container image (e.g., `unprivileged-oss-YYYYMMDD`), change `containerPort: 80` to `containerPort: 8080` as unprivileged containers listen on port 8080.
478+
460479
## Running on EKS with EKS Pod Identities
461480

462481
An alternative way to use the container image on an EKS cluster is to use a service account which can assume a role using [Pod Identities](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).

0 commit comments

Comments
 (0)