NGINX template

This is a NGINX template docker image that can be used as a web server, reverse proxy, load balancer and HTTP cache.

Features

• NGINX - https://nginx.org
• 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 in server

For DEVELOPMENT:

• Install git
• Setup an SSH key (video tutorial)

2. Download or clone the repository

2.1. Prepare projects directory (if not exists) in your server:

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A] or [B]:

A. Clone the repository:

git clone https://github.com/bybatkhuu/server.nginx-template.git && \
    cd server.nginx-template

B. Download source code from releases page.

3. Configure environment

Tip

Skip this step, if you've already configured environment.

3.1. Configure .env file:

Note

Please, check environment variables!

# 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:

Important

Please, check arguments!

# 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, STATGING 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. Validate docker compose configuration:

Warning

If you get an error or warning, check your configuration files (.env or compose.override.yml).

./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:

• https://www.udemy.com/course/nginx-fundamentals
• https://www.baeldung.com/linux/nginx-config-environment-variables
• https://www.youtube.com/watch?v=pkHQCPXaimU
• https://www.nginx.com/blog/avoiding-top-10-nginx-configuration-mistakes
• https://www.nginx.com/nginx-wiki/build/dirhtml/start/topics/tutorials/config_pitfalls
• https://www.digitalocean.com/community/tools/nginx
• https://github.com/fcambus/nginx-resources

Use template files to configure NGINX:

# Copy template file into storage directory:
cp -v ./templates/nginx.conf/[TEMPLATE_BASENAME].conf.template ./volumes/storage/nginx/configs/templates/[CUSTOM_BASENAME].conf.template
# For example, Let's Encrypt HTTPS configuration for example.com domain:
cp -v ./templates/nginx.conf/example.com_https.lets.conf.template ./volumes/storage/nginx/configs/templates/example.com.conf.template

# Edit template file to fit in your nginx configuration:
nano ./volumes/storage/nginx/configs/templates/[CUSTOM_BASENAME].conf.template
# For example:
nano ./volumes/storage/nginx/configs/templates/example.com.conf.template

5. Run docker compose

./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
    docker compose logs -f --tail 100

6. Check service is running

Check the service is running:

./compose.sh list
# Or:
docker compose ps

7. Stop docker compose

./compose.sh stop
# Or:
docker compose down --remove-orphans

👍 ✨

---

Environment Variables

You can use the following environment variables to configure:

.env.example

## --- 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 !!!

Arguments

You can use the following arguments to configure:

-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 file:

    command: ["--https=self"]
    command: ["--https=valid"]
    command: ["--https=lets"]
    command: ["/bin/bash"]

Documentation

• Build docker image

Roadmap

• Add more documentation.

---

References

• Download NGINX - https://nginx.org/en/download.html
• Building NGINX from sources - https://nginx.org/en/docs/configure.html
• NGINX documentation - https://nginx.org/en/docs
• NGINX directives - https://nginx.org/en/docs/dirindex.html
• NGINX variables - https://nginx.org/en/docs/varindex.html
• NGINX config generator (digitalocean) - https://www.digitalocean.com/community/tools/nginx
• NGINX 3rd party modules - https://www.nginx.com/resources/wiki/modules
• NGINX Avoid top 10 mistakes - https://www.nginx.com/blog/avoiding-top-10-nginx-configuration-mistakes
• NGINX Pitfalls and common mistakes - https://www.nginx.com/resources/wiki/start/topics/tutorials/config_pitfalls
• Installing NGINX open source and NGINX Plus - https://www.youtube.com/watch?v=pkHQCPXaimU
• NGINX Proxy Manager - https://nginxproxymanager.com
• NGINX fundamental course - https://www.udemy.com/course/nginx-fundamentals
• NGINX resources - https://github.com/fcambus/nginx-resources
• NGINX config environment variables - https://www.baeldung.com/linux/nginx-config-environment-variables