https://github.com/humblebeeai/server-nginx-template
NGINX Template: A docker image for web server, reverse proxy, load balancer, and HTTP cache with various features like rate limiting, HTTP/2, HTTPS, and more. Ideal for development and test environments.
https://github.com/humblebeeai/server-nginx-template
api-gateway basic-auth docker docker-compose http http-cache http2 https load-balancer nginx rate-limit reverse-proxy scripts server software-engineering template web-server web-socket
Last synced: 28 days ago
JSON representation
NGINX Template: A docker image for web server, reverse proxy, load balancer, and HTTP cache with various features like rate limiting, HTTP/2, HTTPS, and more. Ideal for development and test environments.
- Host: GitHub
- URL: https://github.com/humblebeeai/server-nginx-template
- Owner: humblebeeai
- License: mit
- Created: 2025-05-20T07:19:38.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-27T08:20:23.000Z (5 months ago)
- Last Synced: 2025-12-28T21:34:02.677Z (5 months ago)
- Topics: api-gateway, basic-auth, docker, docker-compose, http, http-cache, http2, https, load-balancer, nginx, rate-limit, reverse-proxy, scripts, server, software-engineering, template, web-server, web-socket
- Language: Shell
- Homepage: https://humblebeeai.github.io/server-nginx-template/
- Size: 799 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# NGINX template
[](https://choosealicense.com/licenses/mit/)
[](https://github.com/humblebeeai/server-nginx-template/actions/workflows/2.build-publish.yml)
[](https://github.com/humblebeeai/server-nginx-template/releases)
[](https://hub.docker.com/r/humblebeeai/nginx/tags)
[](https://hub.docker.com/r/humblebeeai/nginx/tags)
This is a NGINX template docker image that can be used as a web server, reverse proxy, load balancer and HTTP cache.
## ✨ Features
- NGINX -
- NGINX template configuration
- Web server
- Reverse proxy
- Load balancer
- Rate limiting
- HTTP cache
- HTTP header transformations
- HTTP/2 and HTTPS
- Basic authentication
- Websockets
- Docker and docker-compose
---
## 🐤 Getting Started
### 1. 🚧 Prerequisites
- Prepare **server/PC** to run
- Install [**docker** and **docker compose**](https://docs.docker.com/engine/install)
- Docker image: [**humblebeeai/nginx**](https://hub.docker.com/r/humblebeeai/nginx)
For **DEVELOPMENT**:
- Install [**git**](https://git-scm.com/downloads)
- Setup an [**SSH key**](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh)
### 2. 📥 Download or clone the repository
**2.1.** Prepare projects directory (if not exists) in your **server**:
```sh
# Create projects directory:
mkdir -pv ~/workspaces/projects
# Enter into projects directory:
cd ~/workspaces/projects
```
**2.2.** Follow one of the below options **[A]**, **[B]** or **[C]**:
**OPTION A.** Clone the repository:
```sh
git clone https://github.com/humblebeeai/server-nginx-template.git && \
cd server-nginx-template
```
**OPTION B.** Clone the repository (for **DEVELOPMENT**: git + ssh key):
```sh
git clone git@github.com:humblebeeai/server-nginx-template.git && \
cd server-nginx-template
```
**OPTION C.** Download source code from **[releases](https://github.com/humblebeeai/server-nginx-template/releases)** page.
### 3. 🛠 Configure the environment
[TIP] Skip this step, if you've already configured environment!
#### 3.1. 🌎 Configure **`.env`** (environment variables) file
**[IMPORTANT]** Please, check **[environment variables](#-environment-variables)** section for more details.
```sh
# Copy .env.example file into .env file:
cp -v ./.env.example ./.env
# Edit environment variables to fit in your environment:
nano ./.env
```
#### 3.2. 🎺 Configure **`compose.override.yml`** file
[TIP] Skip this step, if you want run with default configuration!
You can use below template **`compose.override.yml`** files for different environments:
- **DEVELOPMENT**: [**`compose.override.dev.yml`**](./templates/compose/compose.override.dev.yml)
- **PRODUCTION/STAGING**: [**`compose.override.prod.yml`**](./templates/compose/compose.override.prod.yml)
```sh
# Copy 'compose.override.[ENV].yml' file to 'compose.override.yml' file:
cp -v ./templates/compose/compose.override.[ENV].yml ./compose.override.yml
# For example, DEVELOPMENT environment:
cp -v ./templates/compose/compose.override.dev.yml ./compose.override.yml
# For example, STAGING or PRODUCTION environment:
cp -v ./templates/compose/compose.override.prod.yml ./compose.override.yml
# Edit 'compose.override.yml' file to fit in your environment:
nano ./compose.override.yml
```
#### 3.3. ✅ Check docker compose configuration is valid
**[WARNING]** If you get an error or warning, check your configuration files (**`.env`** or **`compose.override.yml`**).
```sh
./compose.sh validate
# Or:
docker compose config
```
### 4. 🔧 Configure NGINX
[TIP] Skip this step, if you've already configured NGINX.
**[IMPORTANT]** Please, check nginx configuration and best practices:
-
-
-
-
-
-
-
Use template files in [**`templates/nginx.conf`**](./templates/nginx.conf/static) to configure NGINX:
```sh
# Copy template file into storage directory:
cp -v ./templates/nginx.conf/static/[TEMPLATE_BASENAME].conf ./volumes/storage/nginx/configs/site-enabled/[CUSTOM_BASENAME].conf
# For example, Let's Encrypt HTTPS configuration for example.com domain:
cp -v ./templates/nginx.conf/static/100.example.com.lets.conf ./volumes/storage/nginx/configs/site-enabled/100.example.com.conf
# Edit template file to fit in your nginx configuration:
nano ./volumes/storage/nginx/configs/site-enabled/[CUSTOM_BASENAME].conf
# For example:
nano ./volumes/storage/nginx/configs/site-enabled/100.example.com.conf
```
### 5. 🚀 Start docker compose
**[CAUTION]**:
- If ports are conflicting, you should change ports from [**3. step**](#3--configure-the-environment).
- If container names are conflicting, you should change project directory name (from **`server-nginx-template`** to something else, e.g: `prod.server-nginx-template`) from [**2.2. step**](#2--download-or-clone-the-repository).
```sh
./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
docker compose logs -f --tail 100
```
### 6. 📡 Check service is running and monitor logs
📋 Check service is running:
```sh
./compose.sh list
# Or:
docker compose ps
```
📟 Monitor logs of container:
```sh
./compose.sh logs
# Or:
docker compose logs -f --tail 100
```
🧵 List all running processes inside container:
```sh
./compose.sh ps
# Or:
docker compose top
```
📊 Check resource usage of container:
```sh
./compose.sh stats
# Or:
docker compose stats
```
### 7. 🪂 Stop docker compose
```sh
./compose.sh stop
# Or:
docker compose down --remove-orphans
```
👍
---
## ⚙️ Configuration
### 🌎 Environment Variables
You can use the following environment variables to configure:
[**`.env.example`**](./.env.example):
```sh
## --- NGINX configs --- ##
## NGINX basic auth username and password:
NGINX_BASIC_AUTH_USER=nginx_admin
NGINX_BASIC_AUTH_PASS="NGINX_ADMIN_PASSWORD123" # !!! CHANGE THIS TO RANDOM PASSWORD !!!
## -- Docker configs -- ##
# NGINX_HTTP_PORT=80 # port for bridge network mode
# NGINX_HTTPS_PORT=443 # port for bridge network mode
# NGINX_GRPC_PORT=443 # port for bridge network mode
```
### 🐳 Docker container command arguments
You can use the following arguments to configure:
```txt
-s=*, --https=[self | valid | lets]
Enable HTTPS mode:
self - Self-signed certificate
valid - Valid certificate
lets - Let's Encrypt certificate
-b, --bash, bash, /bin/bash
Run only bash shell.
```
For example as in [**`compose.override.yml`**](./templates/compose/compose.override.dev.yml) file:
```yml
command: ["--https=self"]
command: ["--https=valid"]
command: ["--https=lets"]
command: ["/bin/bash"]
```
---
## 📚 Documentation
- [Build docker image](./docs/docker-build.md)
### 🛤 Roadmap
- Add more documentation.
---
## 📑 References
- Download NGINX -
- Building NGINX from sources -
- NGINX documentation -
- NGINX directives -
- NGINX variables -
- NGINX config generator (digitalocean) -
- NGINX 3rd party modules -
- NGINX Avoid top 10 mistakes -
- NGINX Pitfalls and common mistakes -
- Installing NGINX open source and NGINX Plus -
- NGINX Proxy Manager -
- NGINX fundamental course -
- NGINX resources -
- NGINX config environment variables -
- Docker -
- Docker Compose -