There are many public and private registries available to developers such as Docker Hub, Amazon ECR, and Google Cloud Artifact Registry. But sometimes, instead of relying on an external vendor, you might want to host your images yourself. This gives you more control over how the registry is configured and where the container images are hosted.

This article is a hands-on tutorial that’ll teach you how to self-host a Container Registry.

Table of Contents

• What is a Container Image?

• What is a Container Registry?

• Why you might want to self-host a Container Registry

• How to self-host a Container Registry

• Step 1: Install Docker and Docker Compose on the server

• Step 2: Configure and run the registry container

• Step 3: Run NGINX for handling TLS

• Ready to go!

• Other options

• Conclusion

You will get the most out of this article if you’re already familiar with the tools like Docker and NGINX, and have a general understanding of what a container is.

What is a Container Image?

Before we talk about container registries, let's first understand what a container image is. In a nutshell, a container image is a package that includes all of the files, libraries, and configurations to run a container. They are composed of layers where each layer represents a set of file system changes that add, remove, or modify files.

The most common way to create a container image is to use a Dockerfile.

# build an image
docker build -t pliutau/hello-world:v0 .

# check the images locally
docker images
# REPOSITORY    TAG       IMAGE ID       CREATED          SIZE
# hello-world   latest    9facd12bbcdd   22 seconds ago   11MB

This creates a container image that is stored on your local machine. But what if you want to share this image with others or use it on a different machine? This is where container registries come in.

What is a Container Registry?

A container registry is a storage catalog where you can push and pull container images from. The images are grouped into repositories, which are collections of related images with the same name. For example, on Docker Hub registry, nginx is the name of the repository that contains different versions of the NGINX images.

Some registries are public, meaning that the images hosted on them are accessible to anyone on the Internet. Public registries such as Docker Hub are a good option to host open-source projects.

On the other hand, private registries provide a way to incorporate security and privacy into enterprise container image storage, either hosted in cloud or on-premises. These private registries often come with advanced security features and technical support.

There is a growing list of private registries available such as Amazon ECR, GCP Artifact Registry, GitHub Container Registry, and Docker Hub also offers a private repository feature.

As a developer, you interact with a container registry when using the docker push and docker pull commands.

docker push docker.io/pliutau/hello-world:v0

# In case of Docker Hub we could also skip the registry part
docker push pliutau/hello-world:v0

Let's look at the anatomy of a container image URL:

docker pull docker.io/pliutau/hello-world:v0@sha256:dc11b2...
                |            |            |          |
                ↓            ↓            ↓          ↓
             registry    repository      tag       digest

Why You Might Want to Self-host a Container Registry

Sometimes, instead of relying on a provider like AWS or GCP, you might want to host your images yourself. This keeps your infrastructure internal and makes you less reliant on external vendors. In some heavily regulated industries, this is even a requirement.

A self-hosted registry runs on your own servers, giving you more control over how the registry is configured and where the container images are hosted. At the same time it comes with a cost of maintaining and securing the registry.

How to Self-host a Container Registry

There are several open-source container registry solutions available. The most popular one is officially supported by Docker, called registry, with its implementation for storing and distributing of container images and artifacts. This means that you can run your own registry inside a container.

Here are the main steps to run a registry on a server:

• Install Docker and Docker Compose on the server.

• Configure and run the registry container.

• Run NGINX for handling TLS and forwarding requests to the registry container.

• Setup SSL certificates and configure a domain.

Step 1: Install Docker and Docker Compose on the server

You can use any server that supports Docker. For example, you can use a DigitalOcean Droplet with Ubuntu. For this demo I used Google Cloud Compute to create a VM with Ubuntu.

neofetch

# OS: Ubuntu 20.04.6 LTS x86_64
# CPU: Intel Xeon (2) @ 2.200GHz
# Memory: 3908MiB

Once we're inside our VM, we should install Docker and Docker Compose. Docker Compose is optional, but it makes it easier to manage multi-container applications.

# install docker engine and docker-compose
sudo snap install docker

# verify the installation
docker --version
docker-compose --version

Step 2: Configure and run the registry container

Next we need to configure our registry container. The following compose.yaml file will create a registry container with a volume for storing the images and a volume for storing the password file.

services:
  registry:
    image: registry:latest
    environment:
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/registry.password
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /data
    volumes:
      # Mount the password file
      - ./registry/registry.password:/auth/registry.password
      # Mount the data directory
      - ./registry/data:/data
    ports:
      - 5000

The password file defined in REGISTRY_AUTH_HTPASSWD_PATH is used to authenticate users when they push or pull images from the registry. We should create a password file using the htpasswd command. We should also create a folder for storing the images.

mkdir -p ./registry/data

# install htpasswd
sudo apt install apache2-utils

# create a password file. username: busy, password: bee
htpasswd -Bbn busy bee > ./registry/registry.password

Now we can start the registry container. If you see this message, than everything is working as it should:

docker-compose up

# successfull run should output something like this:
# registry | level=info msg="listening on [::]:5000"

Step 3: Run NGINX for handling TLS

As mentioned earlier, we can use NGINX to handle TLS and forward requests to the registry container.

The Docker Registry requires a valid trusted SSL certificate to work. You can use something like Let's Encrypt or obtain it manually. Make sure you have a domain name pointing to your server (registry.pliutau.com in my case). For this demo I already obtained the certificates using certbot and put it in the ./nginx/certs directory.

Since we're running our Docker Registry in a container, we can run NGINX in a container as well by adding the following service to the compose.yaml file:

services:
  registry:
    # ...
  nginx:
    image: nginx:latest
    depends_on:
      - registry
    volumes:
      # mount the nginx configuration
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      # mount the certificates obtained from Let's Encrypt
      - ./nginx/certs:/etc/nginx/certs
    ports:
      - "443:443"

Our nginx.conf file could look like this:

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    upstream registry {
        server registry:5000;
    }

    server {
        server_name registry.pliutau.com;
        listen 443 ssl;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        location / {
            # important setting for large images
            client_max_body_size                1000m;

            proxy_pass                          http://registry;
            proxy_set_header  Host              $http_host;
            proxy_set_header  X-Real-IP         $remote_addr;
            proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
            proxy_set_header  X-Forwarded-Proto $scheme;
            proxy_read_timeout                  900;
        }
    }
}

Ready to go!

After these steps we can run our registry and Nginx containers.

docker-compose up

Now, on the client side, you can push and pull the images from your registry. But first we need to login to the registry.

docker login registry.pliutau.com

# Username: busy
# Password: bee
# Login Succeeded

Time to build and push our image to our self-hosted registry:

docker build -t registry.pliutau.com/pliutau/hello-world:v0 .

docker push registry.pliutau.com/pliutau/hello-world:v0
# v0: digest: sha256:a56ea4... size: 738

On your server you can check the uploaded images in the data folder:

ls -la ./registry/data/docker/registry/v2/repositories/

Other options

Following the example above, you can also run the registry on Kubernetes. Or you could use a managed registry service like Harbor, which is an open-source registry that provides advanced security features and is compatible with Docker and Kubernetes.

Also, if you want to have a UI for your self-hosted registry, you could use a project like joxit/docker-registry-ui and run it in a separate container.

Conclusion

Self-hosted Container Registries allow you to have complete control over your registry and the way it's deployed. At the same time it comes with a cost of maintaining and securing the registry.

Whatever your reasons for running a self-hosted registry, you now know how it's done. From here you can compare the different options and choose the one that best fits your needs.

You can find the full source code for this demo on GitHub. Also, you can watch it as a video on our YouTube channel.

But unfortunately, they often become targets for hackers and malicious individuals seeking to exploit any vulnerabilities to compromise data and disrupt functionality. As a result, you'll need to prioritize the security of your web server by updating it and implementing safeguards against threats.

To enhance the security of your web server, one effective approach is to use Continous Integration (CI). CI is a DevOps technique that allows the automated merging of code modifications from software engineers into a single repository. This practice enhances code quality, minimizes bugs and speeds up code delivery.

By using CI, you can automate the testing, building, and deployment processes for your web servers’ code and configuration. You can also ensure that your web server consistently maintains a stable state.

In this tutorial, I'll guide you through the process of strengthening the security of your web server by using two popular and powerful tools: NGINX and CircleCI.

NGINX, which is an open source web server, provides a range of features and modules that can greatly enhance the security of your web server. These include SSL/TLS encryption, security headers, and support for HTTP/2.

On the other hand, CircleCI offers both cloud-based and self-hosted options for Continous Integration (CI) and Continuous Delivery (CD), enabling seamless deployment processes.

By following this guide, you will learn how to:

• Configure NGINX to use SSL/TLS encryption and security headers

• Create a GitHub repository and push your NGINX configuration files to it

• Create a CircleCI project and link it to your GitHub repository

• Create a CircleCI configuration file and define your CI pipeline

• Test and deploy your web server with CircleCI

Here is what we'll cover:

• Prerequisites

• Step 1: Configure NGINX to Use SSL/TLS Encryption

• Step 2: Configure NGINX to Include Security Headers

• Step 3: Create a GitHub Repository and Push Your NGINX Configuration

• Step 4: Create a CircleCI Project and Link it to Your GitHub Repository

• Step 5: Create a CircleCI Configuration File and Define Your CI Pipeline

• Step 6: Test and Deploy Your Web Server with CircleCI

Let's get started!

Prerequisites

Before you start this guide, you need to ensure you have the following:

• A web server running NGINX. If you don't have one, you can follow this guide to install NGINX on Ubuntu 20.04. You can also use any other operating system or cloud provider that supports NGINX.

• A GitHub account. If you don't have one, you can sign up for free here.

• A CircleCI account. If you don't have one, you can sign up for free here. You will also need to link your GitHub account to your CircleCI account.

• Some basic knowledge of web development and Linux commands. You should be familiar with the concepts of web servers, SSL/TLS encryption, security headers, and CI. You should also be comfortable with using the command line and editing configuration files.

Once you have these, you are ready to proceed with the next steps.

Step 1: Configure NGINX to Use SSL/TLS Encryption

SSL/TLS encryption ensures the transmission of data between your web server and clients. It safeguards against interception or manipulation of information. It also plays a role in verifying the identity and reliability of your web server.

You need an SSL/TLS certificate to use SSL/TLS for your web server. An SSL/TLS certificate contains information about your web server, such as its domain name, owner, and public key. The validity of the certificate is verified through the unique digital signature from a Certificate Authority (CA).

You can either purchase an SSL/TLS certificate from a commercial CA, such as DigiCert, Symantec, or GlobalSign, or you can just get one for free from a non-profit CA, such as Let's Encrypt. You can also create your own self-signed certificate, but this is not recommended for production use, as it will not be trusted by most browsers and clients.

In this guide, you will use Let's Encrypt to get a free SSL/TLS certificate for your web server. To use Let's Encrypt, you need to install a software client on your web server that can communicate with the CA and perform the necessary tasks.

One of the most common and recommended clients for Let's Encrypt is Certbot. Certbot is a command-line tool that can automatically request, install, and renew certificates for your web server. It can also configure your web server to use the certificates and enable HTTPS.

To install Certbot on your web server, run the following commands:

sudo apt update
sudo apt install certbot python3-certbot-nginx

After installing Certbot, use it to request and install a certificate for your web server. You need to provide your domain name and your email address for the certificate.

To request and install a certificate for your web server, run the following command:

sudo certbot --nginx -d yourdomain.com

Replace yourdomain.com with your actual domain name.

Follow the prompts and answer the questions. Certbot will automatically verify your domain ownership, obtain a certificate, and install it on your web server. It will also ask you whether you want to redirect all HTTP traffic to HTTPS. Choose option 2 to enable the redirection.

After the process is completed, you will see a message like this:

You have now successfully configured NGINX to use SSL/TLS encryption with a certificate from Let's Encrypt. You can now access your web server using HTTPS and see the lock icon in your browser.

You can also test your web server security using online tools, such as SSL Labs. You should see a grade of A or higher.

Note: Let's Encrypt certificates are valid for 90 days. Certbot can automatically renew them for you before they expire.

To enable the automatic renewal, you need to create a CRON job or a systemd timer that runs the following command at least once per day:

sudo certbot renew

You can also test the renewal process manually by running the following command:

sudo certbot renew --dry-run

This will perform a trial run without making any changes.

If you encounter any errors or issues, you can check the Certbot documentation or the Let's Encrypt community forum for help.

Step 2: Configure NGINX to Include Security Headers

Security headers help instruct the browser to apply certain security policies or restrictions when handling your web content. They can prevent or mitigate common web attacks, such as cross-site scripting (XSS), clickjacking, content injection, and more.

In this step, you will be adding security headers to your NGINX configuration. These headers include X Frame Options, X Content Type Options, X XSS Protection, and Content Security Policy.

X-Frame-Options

The X-Frame-Options header tells the browser whether or not to allow your web page to be displayed in a frame, iframe, embed, or object element. This can help you prevent clickjacking attacks, where an attacker overlays a hidden frame on top of your web page and tricks the user into clicking on it.

There are three possible values for this header:

• DENY: This value prevents your web page from being displayed in any frame.

• SAMEORIGIN: This value allows your web page to be displayed in a frame only if the frame is from the same origin as your web page.

• ALLOW-FROM URI: This value allows your web page to be displayed in a frame only if the frame is from the specified URI.

To enable the X-Frame-Options header in NGINX, add the following line to your server block in your NGINX configuration file (/etc/nginx/sites-enabled/example.conf):

add_header X-Frame-Options "SAMEORIGIN";

This will allow your web page to be displayed in a frame only if the frame is from the same origin as your web page. You can change the value to DENY or ALLOW-FROM uri according to your needs.

Save the file and restart NGINX to apply the changes.

X-Content-Type-Options

The X Content Type Options header instructs the browser to perform MIME-type sniffing. This feature attempts to determine the content type of a resource by analyzing its content or file extension.

By using this header you can safeguard against content injection attacks. These attacks involve uploading a file with a content type to exploit the browser’s interpretation of it.

There is only one possible value for this header:

• nosniff: This value prevents the browser from performing MIME type sniffing.

To enable the X-Content-Type-Options header in NGINX, add the following line to your server block in your NGINX configuration file (/etc/nginx/sites-enabled/example.conf):

add_header X-Content-Type-Options "nosniff";

This will prevent the browser from performing MIME type sniffing on your web resources.

Save the file and restart NGINX to apply the changes.

X-XSS-Protection

The X-XSS-Protection header tells the browser to enable or disable its built-in XSS filter, which can detect and block some types of XSS attacks. This can help you prevent XSS attacks, where an attacker injects malicious code into your web page that executes in the browser.

There are three possible values for this header:

• 0: This value disables the XSS filter.

• 1: This value enables the XSS filter and sanitizes the page if an XSS attack is detected.

• 1; mode=block: This value enables the XSS filter and blocks the page if an XSS attack is detected.

To enable the X-XSS-Protection header in NGINX, add the following line to your server block in your NGINX configuration file (/etc/nginx/sites-enabled/example.conf):

add_header X-XSS-Protection "1; mode=block";

This will enable the XSS filter and block the page if an XSS attack is detected. You can change the value to 0 or 1 according to your needs.

Save the file and restart NGINX to apply the changes.

Content-Security-Policy

The Content-Security-Policy header tells the browser to enforce a set of rules that restrict what sources and types of content can be loaded and executed on your web page. This can help you prevent XSS, content injection, and other types of attacks that rely on loading malicious or untrusted content.

The value of this header is a complex policy that consists of multiple directives and values. Each directive specifies a type of content and a list of sources that are allowed or disallowed for that content.

For example, the following policy allows only scripts styles from the same origin, and images from the same origin or yourdomain.com:

Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' yourdomain.com;

The Content-Security-Policy header is very powerful and flexible, but also very complicated and error-prone. You need to carefully design and test your policy to ensure that it does not break your web functionality or introduce new vulnerabilities. You can use tools like CSP Evaluator or CSP Scanner to check and improve your policy.

To enable the Content-Security-Policy header in NGINX, add the following line to your server block in your NGINX configuration file (/etc/nginx/sites-enabled/example.conf):

add_header Content-Security-Policy "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' yourdomain.com;";

This will enforce the policy that you described above. You can change the policy according to your needs.

Save the file and restart NGINX to apply the changes.

Step 3: Create a GitHub Repository and Push Your NGINX Configuration

To create a GitHub repository and push your NGINX configuration files to it, follow these steps:

Create a GitHub repository

First, log in to your GitHub account and go to the GitHub homepage.

Click on the plus icon in the top right corner of the page, and select "New repository" from the dropdown menu.

On the next page, enter a name for your repository in the "Repository name" field. This should be a short and descriptive name that accurately reflects the contents of the repository. For example, you can name it "nginx-config".

In the "Description" field, you can enter a longer description of the repository if you want. This is optional, but it can be helpful to provide more information about the purpose of the repository.

For example, you can write "A repository for storing and managing my NGINX configuration files".

You can set the visibility to whatever you prefer. If you want others to be able to see your work, set it to "Public". Otherwise, set it to "Private".

Leave the "Initialize this repository with a README" option unchecked, as you want to create an empty repository.

Click on the "Create repository" button to create the repository.

Your new empty repository will be created and you will be taken to the repository page.

Push your NGINX configuration files to the GitHub repository

On your web server, navigate to the directory where your NGINX configuration files are located. By default, this is /etc/nginx on most Linux distributions.

Initialize a new Git repository in this directory by running the following command:

git init

This will create a new .git directory in the current directory, which will be used to store all the version control information for your project.

Add all the configuration files that you want to include in the repository by running the following command:

git add .

This will add all the files in the current directory and its subdirectories to the repository. You can also specify individual files to be added by replacing the (.) with the file names, separated by spaces.

Then commit the files to the repository by running the following command:

git commit -m "Initial commit"

This will create the first commit in the repository, which will include all the files that were added in the previous step. The -m flag is used to specify a commit message, which should briefly describe the changes that were made in this commit.

Go back to your GitHub repository page and copy the URL of your repository. You can find it under the "Code" section. It should look something like this:

On your web server, add the URL of your GitHub repository as a remote for your Git repository by running the following command:

git remote add origin https://github.com/username/nginx-config.git

Replace username with your GitHub username and nginx-config with your repository name. The origin is the name of the remote, which you can change to anything you want.

Push your local Git repository to the GitHub repository by running the following command:

git push -u origin master

This will push your master branch, which is the default branch in Git, to the origin remote, which is the GitHub repository that you created. The -u flag is used to set the upstream for your branch, which means that you can use git push or git pull without specifying the remote or the branch in the future.

Enter your GitHub username and password when prompted. If you have enabled two-factor authentication, you will need to use a personal access token instead of your password. You can generate one from your GitHub settings page.

You have successfully created a GitHub repository and pushed your NGINX configuration files to it. You can now view and manage your configuration files on GitHub.

Step 4: Create a CircleCI Project and Link it to Your GitHub Repository

CircleCI is a platform that offers cloud-based and self-hosted options for continuous integration and delivery. It allows you to create and run pipelines that automate and streamline your web server deployment and update process.

To use CircleCI, you need to create a CircleCI project and link it to your GitHub repository. This will enable CircleCI to access your code and configuration files, and trigger builds whenever you push to GitHub.

To create a CircleCI project and link it to your GitHub repository, follow these steps:

Sign up for CircleCI and connect your GitHub account

Start by logging in to your CircleCI account or sign up for free here.

On the CircleCI dashboard, click on the "Create Project" button in the top right corner of the page.

On the next page, select "GitHub" as your version control provider and click on the "Connect with GitHub" button.

On the next page, authorize CircleCI to access your GitHub account by clicking on the "Authorize circleci" button.

On the next page, Enter a “Project Name” and follow the remaining instructions to successfully create a CircleCI project.

Create a CircleCI project and link it to your GitHub repository

Next, create a new SSH key pair in your terminal:

ssh-keygen -t ed25519 -f ~/.ssh/project_key -C email@example.com

Then copy the private key generated:

pbcopy < ~/.ssh/project_key

Next, enter it in the private key field:

You will see a list of your GitHub repositories. Find the repository that you created in the previous step and click on the "Create Project" button next to it.

Now you will see a list of templates for different languages and frameworks. Since you are using Python and Flask, select the "Python" template and click on the "Use this config" button.

On the next page, you will see the generated CircleCI configuration file (config.yml) that defines your pipeline. You can review and edit the file if you want, or leave it as it is for now. Click on the "Start building" button to create the project and link it to your GitHub repository.

Your new CircleCI project will be created and linked to your GitHub repository.

You have now successfully created a CircleCI project and linked it to your GitHub repository. You can now configure and run your pipeline on CircleCI.

Step 5: Create a CircleCI Configuration File and Define Your CI Pipeline

A CircleCI configuration file is a YAML file that defines your CI pipeline. A CI pipeline is a sequence of jobs that run whenever you push changes to your GitHub repository. Each job consists of steps that perform specific tasks, such as running commands, installing dependencies, or deploying your web server.

In this step, you will create a CircleCI configuration file and define your CI pipeline. You will use the Python template that you selected in the previous step as a starting point, and modify it to suit our needs. You will also explain what each step in the pipeline does and how it helps to automate and secure your web server deployment.

Create a CircleCI configuration file

On your web server, navigate to the directory where your NGINX configuration files are located. By default, this is /etc/nginx on most Linux distributions.

Create a new directory called .circleci in this directory by running the following command:

mkdir .circleci

This is where you will store our CircleCI configuration file.

Then create a new file called config.yml in the .circleci directory by running the following command:

touch .circleci/config.yml

This is your CircleCI configuration file.

Open the config.yml file with your preferred text editor and paste the following code:

version: 2.1

jobs:
  build:
    docker:
      - image: cimg/python:3.9
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: |
            pip install -r requirements.txt
      - run:
          name: Run tests
          command: |
            pytest
  deploy:
    machine:
      image: ubuntu-2004:202101-01
    steps:
      - checkout
      - add_ssh_keys:
          fingerprints:
            - "YOUR_FINGERPRINT"
      - run:
          name: Deploy Nginx configuration
          command: |
            scp -r nginx root@YOUR_IP:/etc
            ssh root@YOUR_IP "systemctl restart nginx"

workflows:
  version: 2
  build-and-deploy:
    jobs:
      - build
      - deploy:
          requires:
            - build
          filters:
            branches:
              only: main

This is your CircleCI configuration file that defines your CI pipeline. You will explain each part of the file in the next section.

Finally, fave and close the file.

Define your CI pipeline

Let's go through each part of the config.yml file and see what it does.

• Line 1: This indicates the version of the CircleCI platform you are using. 2.1 is the most recent version.

• Line 3: The jobs level contains a collection of children, representing your jobs. You specify the names for these jobs, for example, build, test, deploy.

• Line 6: This is the Docker image. The example shows cimg/python:3.9, which is a CircleCI-provided image that contains Python 3.9 and other common tools.

• Line 9: The run directive executes a shell command or script. You can specify a name and a command for each run directive.

• Line 11: The command attribute is a list of shell commands that you want to execute. In this case, you are installing the dependencies for your web application using pip.

• Line 12: This is another run directive that runs the tests for your web application using pytest.

• Line 13: deploy is the second child in the jobs collection. This job is responsible for deploying your NGINX configuration to your web server.

• Line 14: This specifies that you are using a machine executor for this job. A machine executor provides a full virtual machine with root access and various tools installed.

• Line 15: This is the machine image. The example shows ubuntu-2004:202101-01, which is a CircleCI-provided image that contains Ubuntu 20.04 and other common tools.

• Line 16: The steps collection is a list of run directives and other commands that you want to execute in this job.

• Line 18: The add_ssh_keys command adds your SSH keys to the machine. You need to provide the fingerprints of the keys that you want to use. You can generate and add SSH keys from your CircleCI settings page.

• Line 21: The command attribute is a list of shell commands that you want to execute. In this case, you are using SCP to copy your NGINX configuration files from the machine to your web server, and SSH to restart the NGINX service on your web server. You need to replace YOUR_FINGERPRINT with the fingerprint of your SSH key, and YOUR_IP with the IP address of your web server.

• Line 24: This indicates the version of the workflow syntax you are using. 2 is the most recent version.

• Line 29: The required attribute specifies the dependencies of this job. In this case, you are saying that the deploy job requires the build job to finish successfully before running.

• Line 30: The filters attribute specifies the conditions for running this job. In this case, you are saying that the deploy job should only run on the main branch of our GitHub repository.

Push your CircleCI configuration file to your GitHub repository

On your web server, add, commit, and push your CircleCI configuration file to your GitHub repository by running the following commands:

git add .circleci/config.yml
git commit -m "Add CircleCI config file"
git push origin main

This will trigger a new build on CircleCI and run your CI pipeline.

Go to your CircleCI dashboard and click on the build-and-deploy workflow.

You can click on each job to see the details and logs of the steps.

Wait for the workflow to finish.

You have successfully created a CircleCI configuration file and defined your CI pipeline. You can now automate and secure your web server deployment with CircleCI. You can also modify and improve your configuration file according to your needs.

Step 6: Test and Deploy Your Web Server with CircleCI

Now that you have created a CircleCI project and a configuration file for your CI pipeline, you can test and deploy your web server with CircleCI. You can trigger and monitor your CI pipeline from the CircleCI web app or the command line. You can also verify that your web server is deployed and secured correctly by using online tools or by accessing your web server using HTTPS.

Trigger and monitor your CI pipeline from the CircleCI web app

To trigger and monitor your CI pipeline from the CircleCI web app, follow these steps:

• Go to the CircleCI dashboard.

• On the dashboard, you will see a list of your projects and pipelines. Find the project that you created in the previous step and click on it.

• On the project page, you will see a list of your branches and workflows. Find the branch that you pushed your CircleCI configuration file to in the previous step and click on the build-and-deploy workflow.

• On the workflow page, you will see a graphical representation of your pipeline, showing the status and duration of each job and step. You can click on each job or step to see the details and logs of the commands that were executed.

• Wait for the workflow to finish. If everything goes well, you will see a green check mark next to each job and step, indicating that they were successful.

You have successfully triggered and monitored your CI pipeline from the CircleCI web app. You can also trigger and monitor your CI pipeline from the command line.

Trigger and monitor your CI pipeline from the command line

To trigger and monitor your CI pipeline from the command line, follow these steps:

• On your web server, navigate to the directory where your NGINX configuration files are located. By default, this is /etc/nginx on most Linux distributions.

• Make some changes to your configuration files, such as adding or removing security headers, and save them.

• Add, commit, and push your changes to your GitHub repository by running the following commands:

git add .
git commit -m "Update Nginx configuration"
git push origin main

This will trigger a new build on CircleCI and run your CI pipeline.

To monitor your CI pipeline from the command line, you can use the CircleCI CLI, which is a tool that allows you to interact with CircleCI from your terminal. You can install the CircleCI CLI by following the instructions on the official website.

After installing the CircleCI CLI, you can use the circleci command to perform various actions, such as listing your projects, pipelines, workflows, jobs, and artifacts. You can also use the --help flag to see the available options and arguments for each command.

To monitor your CI pipeline from the command line, you can use the circleci pipeline command to list and describe your pipelines.

For example, you can run the following command to list the pipelines for your project:

circleci pipeline list --org-slug <VCS>/<your-vcs-org-or-username> --project-slug <VCS>/<your-repo-name>

Replace <VCS> with either gh or bb depending on your version control system. Replace <your-vcs-org-or-username> with your GitHub or Bitbucket organization or username. Replace <your-repo-name> with your repository name. You will see something like this:

You can use the pipeline ID or number to describe a specific pipeline and see its details, such as the status, workflows, jobs, and steps. For example, you can run the following command to describe the latest pipeline for your project:

circleci pipeline describe --org-slug <VCS>/<your-vcs-org-or-username> --project-slug <VCS>/<your-repo-name> --pipeline-number <number>

Replace <number> with the pipeline number that you want to describe.

Wait for the pipeline to finish. If everything goes well, you will see a success message for each job and step, indicating that they were successful.

You have successfully triggered and monitored your CI pipeline from the command line. You can also verify that your web server is deployed and secured correctly.

Verify that your web server is deployed and secured correctly

To verify that your web server is deployed and secured correctly, you can use online tools or access your web server using HTTPS. Here are some examples:

To verify that your web server is using the latest Nginx configuration that you pushed to GitHub, you can use a tool like curl or wget to make a request to your web server and inspect the response headers.

For example, you can run the following command to see the security headers that your web server is sending:

curl -I https://www.yourdomain.com

Replace yourdomain.com with your actual domain name.

You can compare the headers with the ones that you configured in your NGINX configuration file and see if they match.

To verify that your web server is using the SSL/TLS certificate that you installed with Certbot, you can use a tool like SSL Labs or HTBridge to scan your web server and check its SSL/TLS configuration and rating. You can check the details of your certificate, such as the issuer, validity, and chain. You can also check the grade of your SSL/TLS configuration, which should be A or higher.

To verify that your web server is accessible and functional using HTTPS, you can simply open your web browser and visit your web server using HTTPS. For example, you can go to https://www.yourdomain.com and see your web page.

You can check the lock icon in your browser, which indicates that your connection is secure. You can also click on the icon and see the details of your certificate and connection.

Conclusion

In this article, you have learned how to secure your web server using NGINX and CicleCI. NGINX and CircleCI, when used together, can provide a powerful solution for ensuring the continuous security of your web applications.

Stay ahead of the curve by integrating these technologies into your workflow, and empower your team to deliver secure and reliable web services.

Please don't forget to share this guide with your colleagues, friends, and online communities if you find it insightful.

We just published a course on the freeCodeCamp.org YouTube channel that will teach you what you need to know about NGINX. Laith Harb developed this course. He is an experienced software developer and amazing teacher.

This course is designed to offer a comprehensive guide to understanding and using NGINX, a high-performance web server, reverse proxy, and email (IMAP/POP3) proxy.

NGINX is known for its high performance, stability, rich feature set, simple configuration, and low resource consumption. It is widely used to ensure fast and reliable web and application delivery.

Here are some places where NGINX may be used:

• High Traffic Websites: NGINX efficiently handles large volumes of concurrent connections, making it ideal for high-traffic websites.
• Reverse Proxy Applications: It can be used as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache.
• Microservices Architecture: NGINX works well in a microservices architecture for managing communication and load balancing.
• Streaming Media: It's also well-suited for streaming media services.

Course Sections

The course is structured into several informative sections, each focusing on a specific aspect of NGINX:

NGINX Installation

This section provides a step-by-step guide on how to install NGINX on various operating systems, ensuring a smooth and hassle-free start for beginners.

NGINX Terminology

Understanding the key terms and concepts in NGINX is crucial. This section covers the essential terminology to help learners grasp the fundamentals of NGINX architecture and operation.

Serving Static Content

Learn how NGINX can be configured to serve static content, such as HTML, CSS, and JavaScript files, which is a core function of web servers.

Mime Types

This part delves into MIME types and their significance in web development, explaining how NGINX handles different data formats.

Location Context

Explore the 'location' directive in NGINX, which is used to define how to process different requests URLs, a critical aspect for website management.

Rewrites and Redirects

Understand how to implement URL rewrites and redirects in NGINX, a common requirement for website administration and SEO optimization.

NGINX as a Load Balancer

One of the most powerful features of NGINX is its capability to act as a load balancer. This section covers the basics of load balancing and how to set up NGINX for distributing traffic across multiple servers.

Conclusion

With clear explanations, practical examples, and a structured learning path, this course is an excellent opportunity to dive deep into the world of NGINX.

Watch the full course on the freeCodeCamp.org YouTube channel (1-hour watch).

NGINX was first released to the public in 2004 under the terms of the 2-clause BSD license. According to the March 2021 Web Server Survey, NGINX holds 35.3% of the market with a total of 419.6 million sites.

Thanks to tools like NGINXConfig by DigitalOcean and an abundance of pre-written configuration files on the internet, people tend to do a lot of copy-pasting instead of trying to understand when it comes to configuring NGINX.

Trust me, it's not that hard...

I'm not saying that copying code is bad, but copying code without understanding is a big "no no".

Also NGINX is the kind of software that should be configured exactly according to the requirements of the application to be served and available resources on the host.

That's why instead of copying blindly, you should understand and then fine tune what you're copying – and that's where this handbook comes in.

After going through the entire book, you should be able to:

• Understand configuration files generated by popular tools as well as those found in various documentation.
• Configure NGINX as a web server, a reverse proxy server, and a load balancer from scratch.
• Optimize NGINX to get maximum performance out of your server.

Prerequisites

• Familiarity with the Linux terminal and common Unix programs such as ls, cat, ps, grep, find, nproc, ulimit and nano.
• A computer powerful enough to run a virtual machine or a $5 virtual private server.
• Understanding of web applications and a programming language such as JavaScript or PHP.

Table of Contents

• Introduction to NGINX
• How to Install NGINX
  • How to Provision a Local Virtual Machine
  • How to Provision a Virtual Private Server
  • How to Install NGINX on a Provisioned Server or Virtual Machine
• Introduction to NGINX's Configuration Files
• How to Configure a Basic Web Server
  • How to Write Your First Configuration File
  • How to Validate and Reload Configuration Files
  • How to Understand Directives and Contexts in NGINX
  • How to Serve Static Content Using NGINX
  • Static File Type Handling in NGINX
  • How to Include Partial Config Files
• Dynamic Routing in NGINX
  • Location Matches
  • Variables in NGINX
  • Redirects and Rewrites
  • How to Try for Multiple Files
• Logging in NGINX
• How to Use NGINX as a Reverse Proxy
  • Node.js With NGINX
  • PHP With NGINX
• How to Use NGINX as a Load Balancer
• How To Optimize NGINX for Maximum Performance
  • How to Configure Worker Processes and Worker Connections
  • How to Cache Static Content
  • How to Compress Responses
• How to Understand the Main Configuration File
• How To Configure SSL and HTTP/2
  • How To Configure SSL
  • How to Enable HTTP/2
  • How to Enable Server Push
• Conclusion

Project Code

You can find the code for the example projects in the following repository:

Introduction to NGINX

NGINX is a high performance web server developed to facilitate the increasing needs of the modern web. It focuses on high performance, high concurrency, and low resource usage. Although it's mostly known as a web server, NGINX at its core is a reverse proxy server.

NGINX is not the only web server on the market, though. One of its biggest competitors is Apache HTTP Server (httpd), first released back on 1995. In spite of the fact that Apache HTTP Server is more flexible, server admins often prefer NGINX for two main reasons:

• It can handle a higher number of concurrent requests.
• It has faster static content delivery with low resource usage.

I won't go further into the whole Apache vs NGINX debate. But if you wish to learn more about the differences between them in detail, this excellent article from Justin Ellingwood may help.

In fact, to explain NGINX's request handling technique, I would like to quote two paragraphs from Justin's article here:

Nginx came onto the scene after Apache, with more awareness of the concurrency problems that would face sites at scale. Leveraging this knowledge, Nginx was designed from the ground up to use an asynchronous, non-blocking, event-driven connection handling algorithm.

Nginx spawns worker processes, each of which can handle thousands of connections. The worker processes accomplish this by implementing a fast looping mechanism that continuously checks for and processes events. Decoupling actual work from connections allows each worker to concern itself with a connection only when a new event has been triggered.

If that seems a bit complicated to understand, don't worry. Having a basic understanding of the inner workings will suffice for now.

NGINX is faster in static content delivery while staying relatively lighter on resources because it doesn't embed a dynamic programming language processor. When a request for static content comes, NGINX simply responds with the file without running any additional processes.

That doesn't mean that NGINX can't handle requests that require a dynamic programming language processor. In such cases, NGINX simply delegates the tasks to separate processes such as PHP-FPM, Node.js or Python. Then, once that process finishes its work, NGINX reverse proxies the response back to the client.

NGINX is also a lot easier to configure thanks to a configuration file syntax inspired from various scripting languages that results in compact, easily maintainable configuration files.

How to Install NGINX

Installing NGINX on a Linux-based system is pretty straightforward. You can either use a virtual private server running Ubuntu as your playground, or you can provision a virtual machine on your local system using Vagrant.

For the most part, provisioning a local virtual machine will suffice and that's the way I'll be using in this article.

How to Provision a Local Virtual Machine

For those who doesn't know, Vagrant is an open-source tool by Hashicorp that allows you to provision virtual machines using simple configuration files.

For this approach to work, you'll need VirtualBox and Vagrant, so go ahead and install them first. If you need a little warm up on the topic, this tutorial may help.

Create a working directory somewhere in your system with a sensible name. Mine is ~/vagrant/nginx-handbook directory.

Inside the working directory create a file named Vagrantfile and put following content in there:

Vagrant.configure("2") do |config|

    config.vm.hostname = "nginx-handbook-box"

    config.vm.box = "ubuntu/focal64"

    config.vm.define "nginx-handbook-box"

    config.vm.network "private_network", ip: "192.168.20.20"

    config.vm.provider "virtualbox" do |vb|
      vb.cpus = 1
      vb.memory = "1024"
      vb.name = "nginx-handbook"
    end

  end

This Vagrantfile is the configuration file I talked about earlier. It contains information like name of the virtual machine, number of CPUs, size of RAM, the IP address, and more.

To start a virtual machine using this configuration, open your terminal inside the working directory and execute the following command:

vagrant up

# Bringing machine 'nginx-handbook-box' up with 'virtualbox' provider...
# ==> nginx-handbook-box: Importing base box 'ubuntu/focal64'...
# ==> nginx-handbook-box: Matching MAC address for NAT networking...
# ==> nginx-handbook-box: Checking if box 'ubuntu/focal64' version '20210415.0.0' is up to date...
# ==> nginx-handbook-box: Setting the name of the VM: nginx-handbook
# ==> nginx-handbook-box: Clearing any previously set network interfaces...
# ==> nginx-handbook-box: Preparing network interfaces based on configuration...
#     nginx-handbook-box: Adapter 1: nat
#     nginx-handbook-box: Adapter 2: hostonly
# ==> nginx-handbook-box: Forwarding ports...
#     nginx-handbook-box: 22 (guest) => 2222 (host) (adapter 1)
# ==> nginx-handbook-box: Running 'pre-boot' VM customizations...
# ==> nginx-handbook-box: Booting VM...
# ==> nginx-handbook-box: Waiting for machine to boot. This may take a few minutes...
#     nginx-handbook-box: SSH address: 127.0.0.1:2222
#     nginx-handbook-box: SSH username: vagrant
#     nginx-handbook-box: SSH auth method: private key
#     nginx-handbook-box: Warning: Remote connection disconnect. Retrying...
#     nginx-handbook-box: Warning: Connection reset. Retrying...
#     nginx-handbook-box: 
#     nginx-handbook-box: Vagrant insecure key detected. Vagrant will automatically replace
#     nginx-handbook-box: this with a newly generated keypair for better security.
#     nginx-handbook-box: 
#     nginx-handbook-box: Inserting generated public key within guest...
#     nginx-handbook-box: Removing insecure key from the guest if it's present...
#     nginx-handbook-box: Key inserted! Disconnecting and reconnecting using new SSH key...
# ==> nginx-handbook-box: Machine booted and ready!
# ==> nginx-handbook-box: Checking for guest additions in VM...
# ==> nginx-handbook-box: Setting hostname...
# ==> nginx-handbook-box: Configuring and enabling network interfaces...
# ==> nginx-handbook-box: Mounting shared folders...
#     nginx-handbook-box: /vagrant => /home/fhsinchy/vagrant/nginx-handbook

vagrant status

# Current machine states:

# nginx-handbook-box           running (virtualbox)

The output of the vagrant up command may differ on your system, but as long as vagrant status says the machine is running, you're good to go.

Given that the virtual machine is now running, you should be able to SSH into it. To do so, execute the following command:

vagrant ssh nginx-handbook-box

# Welcome to Ubuntu 20.04.2 LTS (GNU/Linux 5.4.0-72-generic x86_64)
# vagrant@nginx-handbook-box:~$

If everything's done correctly you should be logged into your virtual machine, which will be evident by the vagrant@nginx-handbook-box line on your terminal.

This virtual machine will be accessible on http://192.168.20.20 on your local machine. You can even assign a custom domain like http://nginx-handbook.test to the virtual machine by adding an entry to your hosts file:

# on mac and linux terminal
sudo nano /etc/hosts

# on windows command prompt as administrator
notepad c:\windows\system32\drivers\etc\hosts

Now append the following line at the end of the file:

192.168.20.20   nginx-handbook.test

Now you should be able to access the virtual machine on http://nginx-handbook.test URI in your browser.

You can stop or destroy the virtual machine by executing the following commands inside the working directory:

# to stop the virtual machine
vagrant halt

# to destroy the virtual machine
vagrant destroy

If you want to learn about more Vagrant commands, this cheat sheet may come in handy.

Now that you have a functioning Ubuntu virtual machine on your system, all that is left to do is install NGINX.

How to Provision a Virtual Private Server

For this demonstration, I'll use Vultr as my provider but you may use DigitalOcean or whatever provider you like.

Assuming you already have an account with your provider, log into the account and deploy a new server:

On DigitalOcean, it's usually called a droplet. On the next screen, choose a location close to you. I live in Bangladesh which is why I've chosen Singapore:

On the next step, you'll have to choose the operating system and server size. Choose Ubuntu 20.04 and the smallest possible server size:

Although production servers tend to be much bigger and more powerful than this, a tiny server will be more than enough for this article.

Finally, for the last step, put something fitting like nginx-hadnbook-demo-server as the server host and label. You can even leave them empty if you want.

Once you're happy with your choices, go ahead and press the Deploy Now button.

The deployment process may take some time to finish, but once it's done, you'll see the newly created server on your dashboard:

Also pay attention to the Status – it should say Running and not Preparing or Stopped. To connect to the server, you'll need a username and password.

Go into the overview page for your server and there you should see the server's IP address, username, and password:

The generic command for logging into a server using SSH is as follows:

ssh <username>@<ip address>

So in the case of my server, it'll be:

ssh root@45.77.251.108

# Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
# Warning: Permanently added '45.77.251.108' (ECDSA) to the list of known hosts.

# root@45.77.251.108's password: 
# Welcome to Ubuntu 20.04.2 LTS (GNU/Linux 5.4.0-65-generic x86_64)

# root@localhost:~#

You'll be asked if you want to continue connecting to this server or not. Answer with yes and then you'll be asked for the password. Copy the password from the server overview page and paste that into your terminal.

If you do everything correctly you should be logged into your server – you'll see the root@localhost line on your terminal. Here localhost is the server host name, and may differ in your case.

You can access this server directly by its IP address. Or if you own any custom domain, you can use that also.

Throughout the article you'll see me adding test domains to my operating system's hosts file. In case of a real server, you'll have to configure those servers using your DNS provider.

Remember that you'll be charged as long as this server is being used. Although the charge should be very small, I'm warning you anyways. You can destroy the server anytime you want by hitting the trash icon on the server overview page:

If you own a custom domain name, you may assign a sub-domain to this server. Now that you're inside the server, all that is left to is install NGINX.

How to Install NGINX on a Provisioned Server or Virtual Machine

Assuming you're logged into your server or virtual machine, the first thing you should do is performing an update. Execute the following command to do so:

sudo apt update && sudo apt upgrade -y

After the update, install NGINX by executing the following command:

sudo apt install nginx -y

Once the installation is done, NGINX should be automatically registered as a systemd service and should be running. To check, execute the following command:

sudo systemctl status nginx

# ● nginx.service - A high performance web server and a reverse proxy server
#      Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
#      Active: active (running)

If the status says running, then you're good to go. Otherwise you may start the service by executing this command:

sudo systemctl start nginx

Finally for a visual verification that everything is working properly, visit your server/virtual machine with your favorite browser and you should see NGINX's default welcome page:

NGINX is usually installed on the /etc/nginx directory and the majority of our work in the upcoming sections will be done in here.

Congratulations! Bow you have NGINX up and running on your server/virtual machine. Now it's time to jump head first into NGINX.

Introduction to NGINX's Configuration Files

As a web server, NGINX's job is to serve static or dynamic contents to the clients. But how that content are going to be served is usually controlled by configuration files.

NGINX's configuration files end with the .conf extension and usually live inside the /etc/nginx/ directory. Let's begin by cding into this directory and getting a list of all the files:

cd /etc/nginx

ls -lh

# drwxr-xr-x 2 root root 4.0K Apr 21  2020 conf.d
# -rw-r--r-- 1 root root 1.1K Feb  4  2019 fastcgi.conf
# -rw-r--r-- 1 root root 1007 Feb  4  2019 fastcgi_params
# -rw-r--r-- 1 root root 2.8K Feb  4  2019 koi-utf
# -rw-r--r-- 1 root root 2.2K Feb  4  2019 koi-win
# -rw-r--r-- 1 root root 3.9K Feb  4  2019 mime.types
# drwxr-xr-x 2 root root 4.0K Apr 21  2020 modules-available
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 modules-enabled
# -rw-r--r-- 1 root root 1.5K Feb  4  2019 nginx.conf
# -rw-r--r-- 1 root root  180 Feb  4  2019 proxy_params
# -rw-r--r-- 1 root root  636 Feb  4  2019 scgi_params
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 sites-available
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 sites-enabled
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 snippets
# -rw-r--r-- 1 root root  664 Feb  4  2019 uwsgi_params
# -rw-r--r-- 1 root root 3.0K Feb  4  2019 win-utf

Among these files, there should be one named nginx.conf. This is the the main configuration file for NGINX. You can have a look at the content of this file using the cat program:

cat nginx.conf

# user www-data;
# worker_processes auto;
# pid /run/nginx.pid;
# include /etc/nginx/modules-enabled/*.conf;

# events {
#     worker_connections 768;
#     # multi_accept on;
# }

# http {

#     ##
#     # Basic Settings
#     ##

#     sendfile on;
#     tcp_nopush on;
#     tcp_nodelay on;
#     keepalive_timeout 65;
#     types_hash_max_size 2048;
#     # server_tokens off;

#     # server_names_hash_bucket_size 64;
#     # server_name_in_redirect off;

#     include /etc/nginx/mime.types;
#     default_type application/octet-stream;

#     ##
#     # SSL Settings
#     ##

#     ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
#     ssl_prefer_server_ciphers on;

#     ##
#     # Logging Settings
#     ##

#     access_log /var/log/nginx/access.log;
#     error_log /var/log/nginx/error.log;

#     ##
#     # Gzip Settings
#     ##

#     gzip on;

#     # gzip_vary on;
#     # gzip_proxied any;
#     # gzip_comp_level 6;
#     # gzip_buffers 16 8k;
#     # gzip_http_version 1.1;
#     # gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

#     ##
#     # Virtual Host Configs
#     ##

#     include /etc/nginx/conf.d/*.conf;
#     include /etc/nginx/sites-enabled/*;
# }


# #mail {
# #    # See sample authentication script at:
# #    # http://wiki.nginx.org/ImapAuthenticateWithApachePhpScript
# # 
# #    # auth_http localhost/auth.php;
# #    # pop3_capabilities "TOP" "USER";
# #    # imap_capabilities "IMAP4rev1" "UIDPLUS";
# # 
# #    server {
# #        listen     localhost:110;
# #        protocol   pop3;
# #        proxy      on;
# #    }
# # 
# #    server {
# #        listen     localhost:143;
# #        protocol   imap;
# #        proxy      on;
# #    }
# #}

Whoa! That's a lot of stuff. Trying to understand this file at its current state will be a nightmare. So let's rename the file and create a new empty one:

# renames the file
sudo mv nginx.conf nginx.conf.backup

# creates a new file
sudo touch nginx.conf

I highly discourage you from editing the original nginx.conf file unless you absolutely know what you're doing. For learning purposes, you may rename it, but later on, I'll show you how you should go about configuring a server in a real life scenario.

How to Configure a Basic Web Server

In this section of the book, you'll finally get your hands dirty by configuring a basic static web server from the ground up. The goal of this section is to introduce you to the syntax and fundamental concepts of NGINX configuration files.

How to Write Your First Configuration File

Start by opening the newly created nginx.conf file using the nano text editor:

sudo nano /etc/nginx/nginx.conf

Throughout the book, I'll be using nano as my text editor. You may use something more modern if you want to, but in a real life scenario, you're most likely to work using nano or vim on servers instead of anything else. So use this book as an opportunity to sharpen your nano skills. Also the official cheat sheet is there for you to consult whenever you need.

After opening the file, update its content to look like this:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "Bonjour, mon ami!\n";
    }

}

If you have experience building REST APIs then you may guess from the return 200 "Bonjour, mon ami!\n"; line that the server has been configured to respond with a status code of 200 and the message "Bonjour, mon ami!".

Don't worry if you don't understand anything more than that at the moment. I'll explain this file line by line, but first let's see this configuration in action.

How to Validate and Reload Configuration Files

After writing a new configuration file or updating an old one, the first thing to do is check the file for any syntax mistakes. The nginx binary includes an option -t to do just that.

sudo nginx -t

# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

If you have any syntax errors, this command will let you know about them, including the line number.

Although the configuration file is fine, NGINX will not use it. The way NGINX works is it reads the configuration file once and keeps working based on that.

If you update the configuration file, then you'll have to instruct NGINX explicitly to reload the configuration file. There are two ways to do that.

• You can restart the NGINX service by executing the sudo systemctl restart nginx command.
• You can dispatch a reload signal to NGINX by executing the sudo nginx -s reload command.

The -s option is used for dispatching various signals to NGINX. The available signals are stop, quit, reload and reopen. Among the two ways I just mentioned, I prefer the second one simply because it's less typing.

Once you've reloaded the configuration file by executing the nginx -s reload command, you can see it in action by sending a simple get request to the server:

curl -i http://nginx-handbook.test

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 10:03:33 GMT
# Content-Type: text/plain
# Content-Length: 18
# Connection: keep-alive

# Bonjour, mon ami!

The server is responding with a status code of 200 and the expected message. Congratulations on getting this far! Now it's time for some explanation.

How to Understand Directives and Contexts in NGINX

The few lines of code you've written here, although seemingly simple, introduce two of the most important terminologies of NGINX configuration files. They are directives and contexts.

Technically, everything inside a NGINX configuration file is a directive. Directives are of two types:

• Simple Directives
• Block Directives

A simple directive consists of the directive name and the space delimited parameters, like listen, return and others. Simple directives are terminated by semicolons.

Block directives are similar to simple directives, except that instead of ending with semicolons, they end with a pair of curly braces { } enclosing additional instructions.

A block directive capable of containing other directives inside it is called a context, that is events, http and so on. There are four core contexts in NGINX:

• events { } – The events context is used for setting global configuration regarding how NGINX is going to handle requests on a general level. There can be only one events context in a valid configuration file.
• http { } – Evident by the name, http context is used for defining configuration regarding how the server is going to handle HTTP and HTTPS requests, specifically. There can be only one http context in a valid configuration file.
• server { } – The server context is nested inside the http context and used for configuring specific virtual servers within a single host. There can be multiple server contexts in a valid configuration file nested inside the http context. Each server context is considered a virtual host.
• main – The main context is the configuration file itself. Anything written outside of the three previously mentioned contexts is on the main context.

You can treat contexts in NGINX like scopes in other programming languages. There is also a sense of inheritance among them. You can find an alphabetical index of directives on the official NGINX docs.

I've already mentioned that there can be multiple server contexts within a configuration file. But when a request reaches the server, how does NGINX know which one of those contexts should handle the request?

The listen directive is one of the ways to identify the correct server context within a configuration. Consider the following scenario:

http {
    server {
        listen 80;
        server_name nginx-handbook.test;

        return 200 "hello from port 80!\n";
    }


    server {
        listen 8080;
        server_name nginx-handbook.test;

        return 200 "hello from port 8080!\n";
    }
}

Now if you send a request to http://nginx-handbook.test:80 then you'll receive "hello from port 80!" as a response. And if you send a request to http://nginx-handbook.test:8080, you'll receive "hello from port 8080!" as a response:

curl nginx-handbook.test:80

# hello from port 80!

curl nginx-handbook.test:8080

# hello from port 8080!

These two server blocks are like two people holding telephone receivers, waiting to respond when a request reaches one of their numbers. Their numbers are indicated by the listen directives.

Apart from the listen directive, there is also the server_name directive. Consider the following scenario of an imaginary library management application:

http {
    server {
        listen 80;
        server_name library.test;

        return 200 "your local library!\n";
    }


    server {
        listen 80;
        server_name librarian.library.test;

        return 200 "welcome dear librarian!\n";
    }
}

This is a basic example of the idea of virtual hosts. You're running two separate applications under different server names in the same server.

If you send a request to http://library.test then you'll get "your local library!" as a response. If you send a request to http://librarian.library.test, you'll get "welcome dear librarian!" as a response.

curl http://library.test

# your local library!

curl http://librarian.library.test

# welcome dear librarian!

To make this demo work on your system, you'll have to update your hosts file to include these two domain names as well:

192.168.20.20   library.test
192.168.20.20   librarian.library.test

Finally, the return directive is responsible for returning a valid response to the user. This directive takes two parameters: the status code and the string message to be returned.

How to Serve Static Content Using NGINX

Now that you have a good understanding of how to write a basic configuration file for NGINX, let's upgrade the configuration to serve static files instead of plain text responses.

In order to serve static content, you first have to store them somewhere on your server. If you list the files and directory on the root of your server using ls, you'll find a directory called /srv in there:

ls -lh /

# lrwxrwxrwx   1 root    root       7 Apr 16 02:10 bin -> usr/bin
# drwxr-xr-x   3 root    root    4.0K Apr 16 02:13 boot
# drwxr-xr-x  16 root    root    3.8K Apr 21 09:23 dev
# drwxr-xr-x  92 root    root    4.0K Apr 21 09:24 etc
# drwxr-xr-x   4 root    root    4.0K Apr 21 08:04 home
# lrwxrwxrwx   1 root    root       7 Apr 16 02:10 lib -> usr/lib
# lrwxrwxrwx   1 root    root       9 Apr 16 02:10 lib32 -> usr/lib32
# lrwxrwxrwx   1 root    root       9 Apr 16 02:10 lib64 -> usr/lib64
# lrwxrwxrwx   1 root    root      10 Apr 16 02:10 libx32 -> usr/libx32
# drwx------   2 root    root     16K Apr 16 02:15 lost+found
# drwxr-xr-x   2 root    root    4.0K Apr 16 02:10 media
# drwxr-xr-x   2 root    root    4.0K Apr 16 02:10 mnt
# drwxr-xr-x   2 root    root    4.0K Apr 16 02:10 opt
# dr-xr-xr-x 152 root    root       0 Apr 21 09:23 proc
# drwx------   5 root    root    4.0K Apr 21 09:59 root
# drwxr-xr-x  26 root    root     820 Apr 21 09:47 run
# lrwxrwxrwx   1 root    root       8 Apr 16 02:10 sbin -> usr/sbin
# drwxr-xr-x   6 root    root    4.0K Apr 16 02:14 snap
# drwxr-xr-x   2 root    root    4.0K Apr 16 02:10 srv
# dr-xr-xr-x  13 root    root       0 Apr 21 09:23 sys
# drwxrwxrwt  11 root    root    4.0K Apr 21 09:24 tmp
# drwxr-xr-x  15 root    root    4.0K Apr 16 02:12 usr
# drwxr-xr-x   1 vagrant vagrant   38 Apr 21 09:23 vagrant
# drwxr-xr-x  14 root    root    4.0K Apr 21 08:34 var

This /srv directory is meant to contain site-specific data which is served by this system. Now cd into this directory and clone the code repository that comes with this book:

cd /srv

sudo git clone https://github.com/fhsinchy/nginx-handbook-projects.git

Inside the nginx-handbook-projects directory there should a directory called static-demo containing four files in total:

ls -lh /srv/nginx-handbook-projects/static-demo

# -rw-r--r-- 1 root root 960 Apr 21 11:27 about.html
# -rw-r--r-- 1 root root 960 Apr 21 11:27 index.html
# -rw-r--r-- 1 root root 46K Apr 21 11:27 mini.min.css
# -rw-r--r-- 1 root root 19K Apr 21 11:27 the-nginx-handbook.jpg

Now that you have the static content to be served, update your configuration as follows:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;
    }

}

The code is almost the same, except the return directive has now been replaced by a root directive. This directive is used for declaring the root directory for a site.

By writing root /srv/nginx-handbook-projects/static-demo you're telling NGINX to look for files to serve inside the /srv/nginx-handbook-projects/static-demo directory if any request comes to this server. Since NGINX is a web server, it is smart enough to serve the index.html file by default.

Let's see if this works or not. Test and reload the updated configuration file and visit the server. You should be greeted with a somewhat broken HTML site:

Although NGINX has served the index.html file correctly, judging by the look of the three navigation links, it seems like the CSS code is not working.

You may think that there is something wrong in the CSS file. But in reality, the problem is in the configuration file.

Static File Type Handling in NGINX

To debug the issue you're facing right now, send a request for the CSS file to the server:

curl -I http://nginx-handbook/mini.min.css

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 12:17:16 GMT
# Content-Type: text/plain
# Content-Length: 46887
# Last-Modified: Wed, 21 Apr 2021 11:27:06 GMT
# Connection: keep-alive
# ETag: "60800c0a-b727"
# Accept-Ranges: bytes

Pay attention to the Content-Type and see how it says text/plain and not text/css. This means that NGINX is serving this file as plain text instead of as a stylesheet.

Although NGINX is smart enough to find the index.html file by default, it's pretty dumb when it comes to interpreting file types. To solve this problem update your configuration once again:

events {

}

http {

    types {
        text/html html;
        text/css css;
    }

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;
    }
}

The only change we've made to the code is a new types context nested inside the http block. As you may have already guessed from the name, this context is used for configuring file types.

By writing text/html html in this context you're telling NGINX to parse any file as text/html that ends with the html extension.

You may think that configuring the CSS file type should suffice as the HTML is being parsed just fine – but no.

If you introduce a types context in the configuration, NGINX becomes even dumber and only parses the files configured by you. So if you only define the text/css css in this context then NGINX will start parsing the HTML file as plain text.

Validate and reload the newly updated config file and visit the server once again. Send a request for the CSS file once again, and this time the file should be parsed as a text/css file:

curl -I http://nginx-handbook.test/mini.min.css

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 12:29:35 GMT
# Content-Type: text/css
# Content-Length: 46887
# Last-Modified: Wed, 21 Apr 2021 11:27:06 GMT
# Connection: keep-alive
# ETag: "60800c0a-b727"
# Accept-Ranges: bytes

Visit the server for a visual verification, and the site should look better this time:

If you've updated and reloaded the configuration file correctly and you're still seeing the old site, perform a hard refresh.

How to Include Partial Config Files

Mapping file types within the types context may work for small projects, but for bigger projects it can be cumbersome and error-prone.

NGINX provides a solution for this problem. If you list the files inside the /etc/nginx directory once again, you'll see a file named mime.types.

ls -lh /etc/nginx

# drwxr-xr-x 2 root root 4.0K Apr 21  2020 conf.d
# -rw-r--r-- 1 root root 1.1K Feb  4  2019 fastcgi.conf
# -rw-r--r-- 1 root root 1007 Feb  4  2019 fastcgi_params
# -rw-r--r-- 1 root root 2.8K Feb  4  2019 koi-utf
# -rw-r--r-- 1 root root 2.2K Feb  4  2019 koi-win
# -rw-r--r-- 1 root root 3.9K Feb  4  2019 mime.types
# drwxr-xr-x 2 root root 4.0K Apr 21  2020 modules-available
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 modules-enabled
# -rw-r--r-- 1 root root 1.5K Feb  4  2019 nginx.conf
# -rw-r--r-- 1 root root  180 Feb  4  2019 proxy_params
# -rw-r--r-- 1 root root  636 Feb  4  2019 scgi_params
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 sites-available
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 sites-enabled
# drwxr-xr-x 2 root root 4.0K Apr 17 14:42 snippets
# -rw-r--r-- 1 root root  664 Feb  4  2019 uwsgi_params
# -rw-r--r-- 1 root root 3.0K Feb  4  2019 win-utf

Let's have a look at the content of this file:

cat /etc/mime.types

# types {
#     text/html                             html htm shtml;
#     text/css                              css;
#     text/xml                              xml;
#     image/gif                             gif;
#     image/jpeg                            jpeg jpg;
#     application/javascript                js;
#     application/atom+xml                  atom;
#     application/rss+xml                   rss;

#     text/mathml                           mml;
#     text/plain                            txt;
#     text/vnd.sun.j2me.app-descriptor      jad;
#     text/vnd.wap.wml                      wml;
#     text/x-component                      htc;

#     image/png                             png;
#     image/tiff                            tif tiff;
#     image/vnd.wap.wbmp                    wbmp;
#     image/x-icon                          ico;
#     image/x-jng                           jng;
#     image/x-ms-bmp                        bmp;
#     image/svg+xml                         svg svgz;
#     image/webp                            webp;

#     application/font-woff                 woff;
#     application/java-archive              jar war ear;
#     application/json                      json;
#     application/mac-binhex40              hqx;
#     application/msword                    doc;
#     application/pdf                       pdf;
#     application/postscript                ps eps ai;
#     application/rtf                       rtf;
#     application/vnd.apple.mpegurl         m3u8;
#     application/vnd.ms-excel              xls;
#     application/vnd.ms-fontobject         eot;
#     application/vnd.ms-powerpoint         ppt;
#     application/vnd.wap.wmlc              wmlc;
#     application/vnd.google-earth.kml+xml  kml;
#     application/vnd.google-earth.kmz      kmz;
#     application/x-7z-compressed           7z;
#     application/x-cocoa                   cco;
#     application/x-java-archive-diff       jardiff;
#     application/x-java-jnlp-file          jnlp;
#     application/x-makeself                run;
#     application/x-perl                    pl pm;
#     application/x-pilot                   prc pdb;
#     application/x-rar-compressed          rar;
#     application/x-redhat-package-manager  rpm;
#     application/x-sea                     sea;
#     application/x-shockwave-flash         swf;
#     application/x-stuffit                 sit;
#     application/x-tcl                     tcl tk;
#     application/x-x509-ca-cert            der pem crt;
#     application/x-xpinstall               xpi;
#     application/xhtml+xml                 xhtml;
#     application/xspf+xml                  xspf;
#     application/zip                       zip;

#     application/octet-stream              bin exe dll;
#     application/octet-stream              deb;
#     application/octet-stream              dmg;
#     application/octet-stream              iso img;
#     application/octet-stream              msi msp msm;

#     application/vnd.openxmlformats-officedocument.wordprocessingml.document    docx;
#     application/vnd.openxmlformats-officedocument.spreadsheetml.sheet          xlsx;
#     application/vnd.openxmlformats-officedocument.presentationml.presentation  pptx;

#     audio/midi                            mid midi kar;
#     audio/mpeg                            mp3;
#     audio/ogg                             ogg;
#     audio/x-m4a                           m4a;
#     audio/x-realaudio                     ra;

#     video/3gpp                            3gpp 3gp;
#     video/mp2t                            ts;
#     video/mp4                             mp4;
#     video/mpeg                            mpeg mpg;
#     video/quicktime                       mov;
#     video/webm                            webm;
#     video/x-flv                           flv;
#     video/x-m4v                           m4v;
#     video/x-mng                           mng;
#     video/x-ms-asf                        asx asf;
#     video/x-ms-wmv                        wmv;
#     video/x-msvideo                       avi;
# }

The file contains a long list of file types and their extensions. To use this file inside your configuration file, update your configuration to look as follows:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;
    }

}

The old types context has now been replaced with a new include directive. Like the name suggests, this directive allows you to include content from other configuration files.

Validate and reload the configuration file and send a request for the mini.min.css file once again:

curl -I http://nginx-handbook.test/mini.min.css

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 12:29:35 GMT
# Content-Type: text/css
# Content-Length: 46887
# Last-Modified: Wed, 21 Apr 2021 11:27:06 GMT
# Connection: keep-alive
# ETag: "60800c0a-b727"
# Accept-Ranges: bytes

In the section below on how to understand the main configuration file, I'll demonstrate how include can be used to modularize your virtual server configurations.

Dynamic Routing in NGINX

The configuration you wrote in the previous section was a very simple static content server configuration. All it did was match a file from the site root corresponding to the URI the client visits and respond back.

So if the client requests files existing on the root such as index.html, about.html or mini.min.css NGINX will return the file. But if you visit a route such as http://nginx-handbook.test/nothing, it'll respond with the default 404 page:

In this section of the book, you'll learn about the location context, variables, redirects, rewrites and the try_files directive. There will be no new projects in this section but the concepts you learn here will be necessary in the upcoming sections.

Also the configuration will change very frequently in this section, so do not forget to validate and reload the configuration file after every update.

Location Matches

The first concept we'll discuss in this section is the location context. Update the configuration as follows:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location /agatha {
            return 200 "Miss Marple.\nHercule Poirot.\n";
        }
    }
}

We've replaced the root directive with a new location context. This context is usually nested inside server blocks. There can be multiple location contexts within a server context.

If you send a request to http://nginx-handbook.test/agatha, you'll get a 200 response code and list of characters created by Agatha Christie.

curl -i http://nginx-handbook.test/agatha

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 15:59:07 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

# Miss Marple.
# Hercule Poirot.

Now if you send a request to http://nginx-handbook.test/agatha-christie, you'll get the same response:

curl -i http://nginx-handbook.test/agatha-christie

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 15:59:07 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

# Miss Marple.
# Hercule Poirot.

This happens because, by writing location /agatha, you're telling NGINX to match any URI starting with "agatha". This kind of match is called a prefix match.

To perform an exact match, you'll have to update the code as follows:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location = /agatha {
            return 200 "Miss Marple.\nHercule Poirot.\n";
        }
    }

}

Adding an = sign before the location URI will instruct NGINX to respond only if the URL matches exactly. Now if you send a request to anything but /agatha, you'll get a 404 response.

curl -I http://nginx-handbook.test/agatha-christie

# HTTP/1.1 404 Not Found
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:14:29 GMT
# Content-Type: text/html
# Content-Length: 162
# Connection: keep-alive

curl -I http://nginx-handbook.test/agatha

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:15:04 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

Another kind of match in NGINX is the regex match. Using this match you can check location URLs against complex regular expressions.

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location ~ /agatha[0-9] {
            return 200 "Miss Marple.\nHercule Poirot.\n";
        }
    }

}

By replacing the previously used = sign with a ~ sign, you're telling NGINX to perform a regular expression match. Setting the location to ~ /agatha[0-9] means NIGINX will only respond if there is a number after the word "agatha":

curl -I http://nginx-handbook.test/agatha

# HTTP/1.1 404 Not Found
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:14:29 GMT
# Content-Type: text/html
# Content-Length: 162
# Connection: keep-alive

curl -I http://nginx-handbook.test/agatha8

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:15:04 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

A regex match is by default case sensitive, which means that if you capitalize any of the letters, the location won't work:

curl -I http://nginx-handbook.test/Agatha8

# HTTP/1.1 404 Not Found
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:14:29 GMT
# Content-Type: text/html
# Content-Length: 162
# Connection: keep-alive

To turn this into case insensitive, you'll have to add a * after the ~ sign.

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location ~* /agatha[0-9] {
            return 200 "Miss Marple.\nHercule Poirot.\n";
        }
    }

}

That will tell NGINX to let go of type sensitivity and match the location anyways.

curl -I http://nginx-handbook.test/agatha8

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:15:04 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

curl -I http://nginx-handbook.test/Agatha8

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Wed, 21 Apr 2021 16:15:04 GMT
# Content-Type: text/plain
# Content-Length: 29
# Connection: keep-alive

NGINX assigns priority values to these matches, and a regex match has more priority than a prefix match.

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location /Agatha8 {
            return 200 "prefix matched.\n";
        }

        location ~* /agatha[0-9] {
            return 200 "regex matched.\n";
        }
    }

}

Now if you send a request to http://nginx-handbook.test/Agatha8, you'll get the following response:

curl -i http://nginx-handbook.test/Agatha8

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Thu, 22 Apr 2021 08:08:18 GMT
# Content-Type: text/plain
# Content-Length: 15
# Connection: keep-alive

# regex matched.

But this priority can be changed a little. The final type of match in NGINX is a preferential prefix match. To turn a prefix match into a preferential one, you need to include the ^~ modifier before the location URI:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        location ^~ /Agatha8 {
            return 200 "prefix matched.\n";
        }

        location ~* /agatha[0-9] {
            return 200 "regex matched.\n";
        }
    }

}

Now if you send a request to http://nginx-handbook.test/Agatha8, you'll get the following response:

curl -i http://nginx-handbook.test/Agatha8

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Thu, 22 Apr 2021 08:13:24 GMT
# Content-Type: text/plain
# Content-Length: 16
# Connection: keep-alive

# prefix matched.

This time, the prefix match wins. So the list of all the matches in descending order of priority is as follows:

Variables in NGINX

Variables in NGINX are similar to variables in other programming languages. The set directive can be used to declare new variables anywhere within the configuration file:

set $<variable_name> <variable_value>;

# set name "Farhan"
# set age 25
# set is_working true

Variables can be of three types

• String
• Integer
• Boolean

Apart from the variables you declare, there are embedded variables within NGINX modules. An alphabetical index of variables is available in the official documentation.

To see some of the variables in action, update the configuration as follows:

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "Host - $host\nURI - $uri\nArgs - $args\n";
    }

}

Now upon sending a request to the server, you should get a response as follows:

# curl http://nginx-handbook.test/user?name=Farhan

# Host - nginx-handbook.test
# URI - /user
# Args - name=Farhan

As you can see, the $host and $uri variables hold the root address and the requested URI relative to the root, respectively. The $args variable, as you can see, contains all the query strings.

Instead of printing the literal string form of the query strings, you can access the individual values using the $arg variable.

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        set $name $arg_name; # $arg_<query string name>

        return 200 "Name - $name\n";
    }

}

Now the response from the server should look like as follows:

curl http://nginx-handbook.test?name=Farhan

# Name - Farhan

The variables I demonstrated here are embedded in the ngx_http_core_module. For a variable to be accessible in the configuration, NGINX has to be built with the module embedding the variable. Building NGINX from source and usage of dynamic modules is slightly out of scope for this article. But I'll surely write about that in my blog.

Redirects and Rewrites

A redirect in NGINX is same as redirects in any other platform. To demonstrate how redirects work, update your configuration to look like this:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;

        location = /index_page {
                return 307 /index.html;
        }

        location = /about_page {
                return 307 /about.html;
        }
    }
}

Now if you send a request to http://nginx-handbook.test/about_page, you'll be redirected to http://nginx-handbook.test/about.html:

curl -I http://nginx-handbook.test/about_page

# HTTP/1.1 307 Temporary Redirect
# Server: nginx/1.18.0 (Ubuntu)
# Date: Thu, 22 Apr 2021 18:02:04 GMT
# Content-Type: text/html
# Content-Length: 180
# Location: http://nginx-handbook.test/about.html
# Connection: keep-alive

As you can see, the server responded with a status code of 307 and the location indicates http://nginx-handbook.test/about.html. If you visit http://nginx-handbook.test/about_page from a browser, you'll see that the URL will automatically change to http://nginx-handbook.test/about.html.

A rewrite directive, however, works a little differently. It changes the URI internally, without letting the user know. To see it in action, update your configuration as follows:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;

        rewrite /index_page /index.html;

        rewrite /about_page /about.html;
    }
}

Now if you send a request to http://nginx-handbook/about_page URI, you'll get a 200 response code and the HTML code for about.html file in response:

curl -i http://nginx-handbook.test/about_page

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Thu, 22 Apr 2021 18:09:31 GMT
# Content-Type: text/html
# Content-Length: 960
# Last-Modified: Wed, 21 Apr 2021 11:27:06 GMT
# Connection: keep-alive
# ETag: "60800c0a-3c0"
# Accept-Ranges: bytes

# <!DOCTYPE html>
# <html lang="en">
# <head>
#     <meta charset="UTF-8">
#     <meta http-equiv="X-UA-Compatible" content="IE=edge">
#     <meta name="viewport" content="width=device-width, initial-scale=1.0">
#     <title>NGINX Handbook Static Demo</title>
#     <link rel="stylesheet" href="mini.min.css">
#     <style>
#         .container {
#             max-width: 1024px;
#             margin-left: auto;
#             margin-right: auto;
#         }
# 
#         h1 {
#             text-align: center;
#         }
#     </style>
# </head>
# <body class="container">
#     <header>
#         <a class="button" href="index.html">Index</a>
#         <a class="button" href="about.html">About</a>
#         <a class="button" href="nothing">Nothing</a>
#     </header>
#     <div class="card fluid">
#         <img src="./the-nginx-handbook.jpg" alt="The NGINX Handbook Cover Image">
#     </div>
#     <div class="card fluid">
#         <h1>this is the <strong>about.html</strong> file</h1>
#     </div>
# </body>
# </html>

And if you visit the URI using a browser, you'll see the about.html page while the URL remains unchanged:

Apart from the way the URI change is handled, there is another difference between a redirect and rewrite. When a rewrite happens, the server context gets re-evaluated by NGINX. So, a rewrite is a more expensive operation than a redirect.

How to Try for Multiple Files

The final concept I'll be showing in this section is the try_files directive. Instead of responding with a single file, the try_files directive lets you check for the existence of multiple files.

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;

        try_files /the-nginx-handbook.jpg /not_found;

        location /not_found {
                return 404 "sadly, you've hit a brick wall buddy!\n";
        }
    }
}

As you can see, a new try_files directive has been added. By writing try_files /the-nginx-handbook.jpg /not_found; you're instructing NGINX to look for a file named the-nginx-handbook.jpg on the root whenever a request is received. If it doesn't exist, go to the /not_found location.

So now if you visit the server, you'll see the image:

But if you update the configuration to try for a non-existent file such as blackhole.jpg, you'll get a 404 response with the message "sadly, you've hit a brick wall buddy!".

Now the problem with writing a try_files directive this way is that no matter what URL you visit, as long as a request is received by the server and the the-nginx-handbook.jpg file is found on the disk, NGINX will send that back.

And that's why try_files is often used with the $uri NGINX variable.

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;

        try_files $uri /not_found;

        location /not_found {
                return 404 "sadly, you've hit a brick wall buddy!\n";
        }
    }
}

By writing try_files $uri /not_found; you're instructing NGINX to try for the URI requested by the client first. If it doesn't find that one, then try the next one.

So now if you visit http://nginx-handbook.test/index.html you should get the old index.html page. The same goes for the about.html page:

But if you request a file that doesn't exist, you'll get the response from the /not_found location:

curl -i http://nginx-handbook.test/nothing

# HTTP/1.1 404 Not Found
# Server: nginx/1.18.0 (Ubuntu)
# Date: Thu, 22 Apr 2021 20:01:57 GMT
# Content-Type: text/plain
# Content-Length: 38
# Connection: keep-alive

# sadly, you've hit a brick wall buddy!

One thing that you may have already noticed is that if you visit the server root http://nginx-handbook.test, you get the 404 response.

This is because when you're hitting the server root, the $uri variable doesn't correspond to any existing file so NGINX serves you the fallback location. If you want to fix this issue, update your configuration as follows:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-projects/static-demo;

        try_files $uri $uri/ /not_found;

        location /not_found {
                return 404 "sadly, you've hit a brick wall buddy!\n";
        }
    }
}

By writing try_files $uri $uri/ /not_found; you're instructing NGINX to try for the requested URI first. If that doesn't work then try for the requested URI as a directory, and whenever NGINX ends up into a directory it automatically starts looking for an index.html file.

Now if you visit the server, you should get the index.html file just right:

The try_files is the kind of directive that can be used in a number of variations. In the upcoming sections, you'll encounter a few other variations but I would suggest that you do some research on the internet regarding the different usage of this directive by yourself.

Logging in NGINX

By default, NGINX's log files are located inside /var/log/nginx. If you list the content of this directory, you may see something as follows:

ls -lh /var/log/nginx/

# -rw-r----- 1 www-data adm     0 Apr 25 07:34 access.log
# -rw-r----- 1 www-data adm     0 Apr 25 07:34 error.log

Let's begin by emptying the two files.

# delete the old files
sudo rm /var/log/nginx/access.log /var/log/nginx/error.log

# create new files
sudo touch /var/log/nginx/access.log /var/log/nginx/error.log

# reopen the log files
sudo nginx -s reopen

If you do not dispatch a reopen signal to NGINX, it'll keep writing logs to the previously open streams and the new files will remain empty.

Now to make an entry in the access log, send a request to the server.

curl -I http://nginx-handbook.test

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sun, 25 Apr 2021 08:35:59 GMT
# Content-Type: text/html
# Content-Length: 960
# Last-Modified: Sun, 25 Apr 2021 08:35:33 GMT
# Connection: keep-alive
# ETag: "608529d5-3c0"
# Accept-Ranges: bytes

sudo cat /var/log/nginx/access.log 

# 192.168.20.20 - - [25/Apr/2021:08:35:59 +0000] "HEAD / HTTP/1.1" 200 0 "-" "curl/7.68.0"

As you can see, a new entry has been added to the access.log file. Any request to the server will be logged to this file by default. But we can change this behavior using the access_log directive.

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        location / {
            return 200 "this will be logged to the default file.\n";
        }

        location = /admin {
            access_log /var/logs/nginx/admin.log;

            return 200 "this will be logged in a separate file.\n";
        }

        location = /no_logging {
            access_log off;

            return 200 "this will not be logged.\n";
        }
    }
}

The first access_log directive inside the /admin location block instructs NGINX to write any access log of this URI to the /var/logs/nginx/admin.log file. The second one inside the /no_logging location turns off access logs for this location completely.

Validate and reload the configuration. Now if you send requests to these locations and inspect the log files, you should see something like this:

curl http://nginx-handbook.test/no_logging
# this will not be logged

sudo cat /var/log/nginx/access.log
# empty

curl http://nginx-handbook.test/admin
# this will be logged in a separate file.

sudo cat /var/log/nginx/access.log
# empty

sudo cat /var/log/nginx/admin.log 
# 192.168.20.20 - - [25/Apr/2021:11:13:53 +0000] "GET /admin HTTP/1.1" 200 40 "-" "curl/7.68.0"

curl  http://nginx-handbook.test/
# this will be logged to the default file.

sudo cat /var/log/nginx/access.log 
# 192.168.20.20 - - [25/Apr/2021:11:15:14 +0000] "GET / HTTP/1.1" 200 41 "-" "curl/7.68.0"

The error.log file, on the other hand, holds the failure logs. To make an entry to the error.log, you'll have to make NGINX crash. To do so, update your configuration as follows:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "..." "...";
    }

}

As you know, the return directive takes only two parameters – but we've given three here. Now try reloading the configuration and you'll be presented with an error message:

sudo nginx -s reload

# nginx: [emerg] invalid number of arguments in "return" directive in /etc/nginx/nginx.conf:14

Check the content of the error log and the message should be present there as well:

sudo cat /var/log/nginx/error.log 

# 2021/04/25 08:35:45 [notice] 4169#4169: signal process started
# 2021/04/25 10:03:18 [emerg] 8434#8434: invalid number of arguments in "return" directive in /etc/nginx/nginx.conf:14

Error messages have levels. A notice entry in the error log is harmless, but an emerg or emergency entry has to be addressed right away.

There are eight levels of error messages:

• debug – Useful debugging information to help determine where the problem lies.
• info – Informational messages that aren't necessary to read but may be good to know.
• notice – Something normal happened that is worth noting.
• warn – Something unexpected happened, however is not a cause for concern.
• error – Something was unsuccessful.
• crit – There are problems that need to be critically addressed.
• alert – Prompt action is required.
• emerg – The system is in an unusable state and requires immediate attention.

By default, NGINX records all level of messages. You can override this behavior using the error_log directive. If you want to set the minimum level of a message to be warn, then update your configuration file as follows:

events {

}

http {

    include /etc/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        error_log /var/log/error.log warn;

        return 200 "..." "...";
    }

}

Validate and reload the configuration, and from now on only messages with a level of warn or above will be logged.

cat /var/log/nginx/error.log

# 2021/04/25 11:27:02 [emerg] 12769#12769: invalid number of arguments in "return" directive in /etc/nginx/nginx.conf:16

Unlike the previous output, there are no notice entries here. emerg is a higher level error than warn and that's why it has been logged.

For most projects, leaving the error configuration as it is should be fine. The only suggestion I have is to set the minimum error level to warn. This way you won't have to look at unnecessary entries in the error log.

But if you want to learn more about customizing logging in NGINX, this link to the official docs may help.

How to Use NGINX as a Reverse Proxy

When configured as a reverse proxy, NGINX sits between the client and a back end server. The client sends requests to NGINX, then NGINX passes the request to the back end.

Once the back end server finishes processing the request, it sends it back to NGINX. In turn, NGINX returns the response to the client.

During the whole process, the client doesn't have any idea about who's actually processing the request. It sounds complicated in writing, but once you do it for yourself you'll see how easy NGINX makes it.

Let's see a very basic and impractical example of a reverse proxy:

events {

}

http {

    include /etc/nginx/mime.types;

    server {
        listen 80;
        server_name nginx.test;

        location / {
                proxy_pass "https://nginx.org/";
        }
    }
}

Apart from validating and reloading the configuration, you'll also have to add this address to your hosts file to make this demo work on your system:

192.168.20.20   nginx.test

Now if you visit http://nginx.test, you'll be greeted by the original https://nginx.org site while the URI remains unchanged.

You should be even able to navigate around the site to an extent. If you visit http://nginx.test/en/docs/ you should get the http://nginx.org/en/docs/ page in response.

So as you can see, at a basic level, the proxy_pass directive simply passes a client's request to a third party server and reverse proxies the response to the client.

Node.js With NGINX

Now that you know how to configure a basic reverse proxy server, you can serve a Node.js application reverse proxied by NGINX. I've added a demo application inside the repository that comes with this article.

I'm assuming that you have experience with Node.js and know how to start a Node.js application using PM2.

If you've already cloned the repository inside /srv/nginx-handbook-projects then the node-js-demo project should be available in the /srv/nginx-handbook-projects/node-js-demo directory.

For this demo to work, you'll need to install Node.js on your server. You can do that following the instructions found here.

The demo application is a simple HTTP server that responds with a 200 status code and a JSON payload. You can start the application by simply executing node app.js but a better way is to use PM2.

For those of you who don't know, PM2 is a daemon process manager widely used in production for Node.js applications. If you want to learn more, this link may help.

Install PM2 globally by executing sudo npm install -g pm2. After the installation is complete, execute following command while being inside the /srv/nginx-handbook-projects/node-js-demo directory:

pm2 start app.js

# [PM2] Process successfully started
# ┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
# │ id │ name               │ mode     │ ↺    │ status    │ cpu      │ memory   │
# ├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
# │ 0  │ app                │ fork     │ 0    │ online    │ 0%       │ 21.2mb   │
# └────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

Alternatively you can also do pm2 start /srv/nginx-handbook-projects/node-js-demo/app.js from anywhere on the server. You can stop the application by executing the pm2 stop app command.

The application should be running now but should not be accessible from outside of the server. To verify if the application is running or not, send a get request to http://localhost:3000 from inside your server:

curl -i localhost:3000

# HTTP/1.1 200 OK
# X-Powered-By: Express
# Content-Type: application/json; charset=utf-8
# Content-Length: 62
# ETag: W/"3e-XRN25R5fWNH2Tc8FhtUcX+RZFFo"
# Date: Sat, 24 Apr 2021 12:09:55 GMT
# Connection: keep-alive
# Keep-Alive: timeout=5

# { "status": "success", "message": "You're reading The NGINX Handbook!" }

If you get a 200 response, then the server is running fine. Now to configure NGINX as a reverse proxy, open your configuration file and update its content as follows:

events {

}

http {
    listen 80;
    server_name nginx-handbook.test

    location / {
        proxy_pass http://localhost:3000;
    }
}

Nothing new to explain here. You're just passing the received request to the Node.js application running at port 3000. Now if you send a request to the server from outside you should get a response as follows:

curl -i http://nginx-handbook.test

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sat, 24 Apr 2021 14:58:01 GMT
# Content-Type: application/json
# Transfer-Encoding: chunked
# Connection: keep-alive

# { "status": "success", "message": "You're reading The NGINX Handbook!" }

Although this works for a basic server like this, you may have to add a few more directives to make it work in a real world scenario depending on your application's requirements.

For example, if your application handles web socket connections, then you should update the configuration as follows:

events {

}

http {
    listen 80;
    server_name nginx-handbook.test

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
    }
}

The proxy_http_version directive sets the HTTP version for the server. By default it's 1.0, but web socket requires it to be at least 1.1. The proxy_set_header directive is used for setting a header on the back-end server. Generic syntax for this directive is as follows:

proxy_set_header <header name> <header value>

So, by writing proxy_set_header Upgrade $http_upgrade; you're instructing NGINX to pass the value of the $http_upgrade variable as a header named Upgrade – same for the Connection header.

If you would like to learn more about web socket proxying, this link to the official NGINX docs may help.

Depending on the headers required by your application, you may have to set more of them. But the above mentioned configuration is very commonly used to serve Node.js applications.

PHP With NGINX

PHP and NGINX go together like bread and butter. After all the E and the P in the LEMP stack stand for NGINX and PHP.

I'm assuming you have experience with PHP and know how to run a PHP application.

I've already included a demo PHP application in the repository that comes with this article. If you've already cloned it in the /srv/nginx-handbook-projects directory, then the application should be inside /srv/nginx-handbook-projects/php-demo.

For this demo to work, you'll have to install a package called PHP-FPM. To install the package, you can execute following command:

sudo apt install php-fpm -y

To test out the application, start a PHP server by executing the following command while inside the /srv/nginx-handbook-projects/php-demo directory:

php -S localhost:8000

# [Sat Apr 24 16:17:36 2021] PHP 7.4.3 Development Server (http://localhost:8000) started

Alternatively you can also do php -S localhost:8000 /srv/nginx-handbook-projects/php-demo/index.php from anywhere on the server.

The application should be running at port 8000 but it can not be accessed from the outside of the server. To verify, send a get request to http://localhost:8000 from inside your server:

curl -I localhost:8000

# HTTP/1.1 200 OK
# Host: localhost:8000
# Date: Sat, 24 Apr 2021 16:22:42 GMT
# Connection: close
# X-Powered-By: PHP/7.4.3
# Content-type: application/json

# {"status":"success","message":"You're reading The NGINX Handbook!"}

If you get a 200 response then the server is running fine. Just like the Node.js configuration, now you can simply proxy_pass the requests to localhost:8000 – but with PHP, there is a better way.

The FPM part in PHP-FPM stands for FastCGI Process Module. FastCGI is a protocol just like HTTP for exchanging binary data. This protocol is slightly faster than HTTP and provides better security.

To use FastCGI instead of HTTP, update your configuration as follows:

events {

}

http {

      include /etc/nginx/mime.types;

      server {

          listen 80;
          server_name nginx-handbook.test;
          root /srv/nginx-handbook-projects/php-demo;

          index index.php;

          location / {
              try_files $uri $uri/ =404;
          }

          location ~ \.php$ {
              fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
              fastcgi_param REQUEST_METHOD $request_method;
              fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      }
   }
}

Let's begin with the new index directive. As you know, NGINX by default looks for an index.html file to serve. But in the demo-project, it's called index.php. So by writing index index.php, you're instructing NGINX to use the index.php file as root instead.

This directive can accept multiple parameters. If you write something like index index.php index.html, NGINX will first look for index.php. If it doesn't find that file, it will look for an index.html file.

The try_files directive inside the first location context is the same as you've seen in a previous section. The =404 at the end indicates the error to throw if none of the files are found.

The second location block is the place where the main magic happens. As you can see, we've replaced the proxy_pass directive by a new fastcgi_pass. As the name suggests, it's used to pass a request to a FastCGI service.

The PHP-FPM service by default runs on port 9000 of the host. So instead of using a Unix socket like I've done here, you can pass the request to http://localhost:9000 directly. But using a Unix socket is more secure.

If you have multiple PHP-FPM versions installed, you can simply list all the socket file locations by executing the following command:

sudo find / -name *fpm.sock

# /run/php/php7.4-fpm.sock
# /run/php/php-fpm.sock
# /etc/alternatives/php-fpm.sock
# /var/lib/dpkg/alternatives/php-fpm.sock

The /run/php/php-fpm.sock file refers to the latest version of PHP-FPM installed on your system. I prefer using the one with the version number. This way even if PHP-FPM gets updated, I'll be certain about the version I'm using.

Unlike passing requests through HTTP, passing requests through FPM requires us to pass some extra information.

The general way of passing extra information to the FPM service is using the fastcgi_param directive. At the very least, you'll have to pass the request method and the script name to the back-end service for the proxying to work.

The fastcgi_param REQUEST_METHOD $request_method; passes the request method to the back-end and the fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; line passes the exact location of the PHP script to run.

At this state, your configuration should work. To test it out, visit your server and you should be greeted by something like this:

Well, that's weird. A 500 error means NGINX has crashed for some reason. This is where the error logs can come in handy. Let's have a look at the last entry in the error.log file:

tail -n 1 /var/log/nginx/error.log

# 2021/04/24 17:15:17 [crit] 17691#17691: *21 connect() to unix:/var/run/php/php7.4-fpm.sock failed (13: Permission denied) while connecting to upstream, client: 192.168.20.20, server: nginx-handbook.test, request: "GET / HTTP/1.1", upstream: "fastcgi://unix:/var/run/php/php7.4-fpm.sock:", host: "nginx-handbook.test"

Seems like the NGINX process is being denied permission to access the PHP-FPM process.

One of the main reasons for getting a permission denied error is user mismatch. Have a look at the user owning the NGINX worker process.

ps aux | grep nginx

# root         677  0.0  0.4   8892  4260 ?        Ss   14:31   0:00 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
# nobody     17691  0.0  0.3   9328  3452 ?        S    17:09   0:00 nginx: worker process
# vagrant    18224  0.0  0.2   8160  2552 pts/0    S+   17:19   0:00 grep --color=auto nginx

As you can see, the process is currently owned by nobody. Now inspect the PHP-FPM process.

# ps aux | grep php

# root       14354  0.0  1.8 195484 18924 ?        Ss   16:11   0:00 php-fpm: master process (/etc/php/7.4/fpm/php-fpm.conf)
# www-data   14355  0.0  0.6 195872  6612 ?        S    16:11   0:00 php-fpm: pool www
# www-data   14356  0.0  0.6 195872  6612 ?        S    16:11   0:00 php-fpm: pool www
# vagrant    18296  0.0  0.0   8160   664 pts/0    S+   17:20   0:00 grep --color=auto php

This process, on the other hand, is owned by the www-data user. This is why NGINX is being denied access to this process.

To solve this issue, update your configuration as follows:

user www-data;

events {

}

http {

      include /etc/nginx/mime.types;

      server {

          listen 80;
          server_name nginx-handbook.test;
          root /srv/nginx-handbook-projects/php-demo;

          index index.php;

          location / {
              try_files $uri $uri/ =404;
          }

          location ~ \.php$ {
              fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
              fastcgi_param REQUEST_METHOD $request_method;
              fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
      }
   }
}

The user directive is responsible for setting the owner for the NGINX worker processes. Now inspect the the NGINX process once again:

# ps aux | grep nginx

# root         677  0.0  0.4   8892  4264 ?        Ss   14:31   0:00 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
# www-data   20892  0.0  0.3   9292  3504 ?        S    18:10   0:00 nginx: worker process
# vagrant    21294  0.0  0.2   8160  2568 pts/0    S+   18:18   0:00 grep --color=auto nginx

Undoubtedly the process is now owned by the www-data user. Send a request to your server to check if it's working or not:

# curl -i http://nginx-handbook.test

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sat, 24 Apr 2021 18:22:24 GMT
# Content-Type: application/json
# Transfer-Encoding: chunked
# Connection: keep-alive

# {"status":"success","message":"You're reading The NGINX Handbook!"}

If you get a 200 status code with a JSON payload, you're good to go.

This simple configuration is fine for the demo application, but in real-life projects you'll have to pass some additional parameters.

For this reason, NGINX includes a partial configuration called fastcgi_params. This file contains a list of the most common FastCGI parameters.

cat /etc/nginx/fastcgi_params

# fastcgi_param  QUERY_STRING       $query_string;
# fastcgi_param  REQUEST_METHOD     $request_method;
# fastcgi_param  CONTENT_TYPE       $content_type;
# fastcgi_param  CONTENT_LENGTH     $content_length;

# fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
# fastcgi_param  REQUEST_URI        $request_uri;
# fastcgi_param  DOCUMENT_URI       $document_uri;
# fastcgi_param  DOCUMENT_ROOT      $document_root;
# fastcgi_param  SERVER_PROTOCOL    $server_protocol;
# fastcgi_param  REQUEST_SCHEME     $scheme;
# fastcgi_param  HTTPS              $https if_not_empty;

# fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
# fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

# fastcgi_param  REMOTE_ADDR        $remote_addr;
# fastcgi_param  REMOTE_PORT        $remote_port;
# fastcgi_param  SERVER_ADDR        $server_addr;
# fastcgi_param  SERVER_PORT        $server_port;
# fastcgi_param  SERVER_NAME        $server_name;

# PHP only, required if PHP was built with --enable-force-cgi-redirect
# fastcgi_param  REDIRECT_STATUS    200;

As you can see, this file also contains the REQUEST_METHOD parameter. Instead of passing that manually, you can just include this file in your configuration:

user www-data;

events {

}

http {

      include /etc/nginx/mime.types;

      server {

          listen 80;
          server_name nginx-handbook.test;
          root /srv/nginx-handbook-projects/php-demo;

          index index.php;

          location / {
              try_files $uri $uri/ =404;
          }

          location ~ \.php$ {
              fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
              fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
              include /etc/nginx/fastcgi_params;
      }
   }
}

Your server should behave just the same. Apart from the fastcgi_params file, you may also come across the fastcgi.conf file which contains a slightly different set of parameters. I would suggest that you avoid that due to some inconsistencies with its behavior.

How to Use NGINX as a Load Balancer

Thanks to the reverse proxy design of NGINX, you can easily configure it as a load balancer.

I've already added a demo to the repository that comes with this article. If you've already cloned the repository inside the /srv/nginx-handbook-projects/ directory then the demo should be in the /srv/nginx-handbook-projects/load-balancer-demo/ directory.

In a real life scenario, load balancing may be required on large scale projects distributed across multiple servers. But for this simple demo, I've created three very simple Node.js servers responding with a server number and 200 status code.

For this demo to work, you'll need Node.js installed on the server. You can find instructions in this link to help you get it installed.

Apart from this, you'll also need PM2 for daemonizing the Node.js servers provided in this demo.

If you haven't already, install PM2 by executing sudo npm install -g pm2. After the installation finishes, execute the following commands to start the three Node.js servers:

pm2 start /srv/nginx-handbook-projects/load-balancer-demo/server-1.js

pm2 start /srv/nginx-handbook-projects/load-balancer-demo/server-2.js

pm2 start /srv/nginx-handbook-projects/load-balancer-demo/server-3.js

pm2 list

# ┌────┬────────────────────┬──────────┬──────┬───────────┬──────────┬──────────┐
# │ id │ name               │ mode     │ ↺    │ status    │ cpu      │ memory   │
# ├────┼────────────────────┼──────────┼──────┼───────────┼──────────┼──────────┤
# │ 0  │ server-1           │ fork     │ 0    │ online    │ 0%       │ 37.4mb   │
# │ 1  │ server-2           │ fork     │ 0    │ online    │ 0%       │ 37.2mb   │
# │ 2  │ server-3           │ fork     │ 0    │ online    │ 0%       │ 37.1mb   │
# └────┴────────────────────┴──────────┴──────┴───────────┴──────────┴──────────┘

Three Node.js servers should be running on localhost:3001, localhost:3002, localhost:3003 respectively.

Now update your configuration as follows:

events {

}

http {

    upstream backend_servers {
        server localhost:3001;
        server localhost:3002;
        server localhost:3003;
    }

    server {

        listen 80;
        server_name nginx-handbook.test;

        location / {
            proxy_pass http://backend_servers;
        }
    }
}

The configuration inside the server context is the same as you've already seen. The upstream context, though, is new. An upstream in NGINX is a collection of servers that can be treated as a single backend.

So the three servers you started using PM2 can be put inside a single upstream and you can let NGINX balance the load between them.

To test out the configuration, you'll have to send a number of requests to the server. You can automate the process using a while loop in bash:

while sleep 0.5; do curl http://nginx-handbook.test; done

# response from server - 2.
# response from server - 3.
# response from server - 1.
# response from server - 2.
# response from server - 3.
# response from server - 1.
# response from server - 2.
# response from server - 3.
# response from server - 1.
# response from server - 2.

You can cancel the loop by hitting Ctrl + C on your keyboard. As you can see from the responses from the server, NGINX is load balancing the servers automatically.

Of course, depending on the project scale, load balancing can be a lot more complicated than this. But the goal of this article is to get you started, and I believe you now have a basic understanding of load balancing with NGINX. You can stop the three running server by executing pm2 stop server-1 server-2 server-3 command (and it's a good idea here).

How to Optimize NGINX for Maximum Performance

In this section of the article, you'll learn about a number of ways to get the maximum performance from your server.

Some of these methods will be application-specific, which means they'll probably need tweaking considering your application requirements. But some of them will be general optimization techniques.

Just like the previous sections, changes in configuration will be frequesnt in this one, so don't forget to validate and reload your configuration file every time.

How to Configure Worker Processes and Worker Connections

As I've already mentioned in a previous section, NGINX can spawn multiple worker processes capable of handling thousands of requests each.

sudo systemctl status nginx

# ● nginx.service - A high performance web server and a reverse proxy server
#      Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
#      Active: active (running) since Sun 2021-04-25 08:33:11 UTC; 5h 45min ago
#        Docs: man:nginx(8)
#    Main PID: 3904 (nginx)
#       Tasks: 2 (limit: 1136)
#      Memory: 3.2M
#      CGroup: /system.slice/nginx.service
#              ├─ 3904 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
#              └─16443 nginx: worker process

As you can see, right now there is only one NGINX worker process on the system. This number, however, can be changed by making a small change to the configuration file.

worker_processes 2;

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "worker processes and worker connections configuration!\n";
    }
}

The worker_process directive written in the main context is responsible for setting the number of worker processes to spawn. Now check the NGINX service once again and you should see two worker processes:

sudo systemctl status nginx

# ● nginx.service - A high performance web server and a reverse proxy server
#      Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
#      Active: active (running) since Sun 2021-04-25 08:33:11 UTC; 5h 54min ago
#        Docs: man:nginx(8)
#     Process: 22610 ExecReload=/usr/sbin/nginx -g daemon on; master_process on; -s reload (code=exited, status=0/SUCCESS)
#    Main PID: 3904 (nginx)
#       Tasks: 3 (limit: 1136)
#      Memory: 3.7M
#      CGroup: /system.slice/nginx.service
#              ├─ 3904 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
#              ├─22611 nginx: worker process
#              └─22612 nginx: worker process

Setting the number of worker processes is easy, but determining the optimal number of worker processes requires a bit more work.

The worker processes are asynchronous in nature. This means that they will process incoming requests as fast as the hardware can.

Now consider that your server runs on a single core processor. If you set the number of worker processes to 1, that single process will utilize 100% of the CPU capacity. But if you set it to 2, the two processes will be able to utilize 50% of the CPU each. So increasing the number of worker processes doesn't mean better performance.

A rule of thumb in determining the optimal number of worker processes is number of worker process = number of CPU cores.

If you're running on a server with a dual core CPU, the number of worker processes should be set to 2. In a quad core it should be set to 4...and you get the idea.

Determining the number of CPUs on your server is very easy on Linux.

nproc

# 1

I'm on a single CPU virtual machine, so the nproc detects that there's one CPU. Now that you know the number of CPUs, all that is left to do is set the number on the configuration.

That's all well and good, but every time you upscale the server and the CPU number changes, you'll have to update the server configuration manually.

NGINX provides a better way to deal with this issue. You can simply set the number of worker processes to auto and NGINX will set the number of processes based on the number of CPUs automatically.

worker_processes auto;

events {

}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "worker processes and worker connections configuration!\n";
    }
}

Inspect the NGINX process once again:

sudo systemctl status nginx

# ● nginx.service - A high performance web server and a reverse proxy server
#      Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
#      Active: active (running) since Sun 2021-04-25 08:33:11 UTC; 6h ago
#        Docs: man:nginx(8)
#     Process: 22610 ExecReload=/usr/sbin/nginx -g daemon on; master_process on; -s reload (code=exited, status=0/SUCCESS)
#    Main PID: 3904 (nginx)
#       Tasks: 2 (limit: 1136)
#      Memory: 3.2M
#      CGroup: /system.slice/nginx.service
#              ├─ 3904 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
#              └─23659 nginx: worker process

The number of worker processes is back to one again, because that's what is optimal for this server.

Apart from the worker processes there is also the worker connection, indicating the highest number of connections a single worker process can handle.

Just like the number of worker processes, this number is also related to the number of your CPU core and the number of files your operating system is allowed to open per core.

Finding out this number is very easy on Linux:

ulimit -n

# 1024

Now that you have the number, all that is left is to set it in the configuration:

worker_processes auto;

events {
    worker_connections 1024;
}

http {

    server {

        listen 80;
        server_name nginx-handbook.test;

        return 200 "worker processes and worker connections configuration!\n";
    }
}

The worker_connections directive is responsible for setting the number of worker connections in a configuration. This is also the first time you're working with the events context.

In a previous section, I mentioned that this context is used for setting values used by NGINX on a general level. The worker connections configuration is one such example.

How to Cache Static Content

The second technique for optimizing your server is caching static content. Regardless of the application you're serving, there is always a certain amount of static content being served, such as stylesheets, images, and so on.

Considering that this content is not likely to change very frequently, it's a good idea to cache them for a certain amount of time. NGINX makes this task easy as well.

worker_processes auto;

events {
    worker_connections 1024;
}

http {

    include /env/nginx/mime.types;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-demo/static-demo;

        location ~* \.(css|js|jpg)$ {
            access_log off;

            add_header Cache-Control public;
            add_header Pragma public;
            add_header Vary Accept-Encoding;
            expires 1M;
        }
    }
}

By writing location ~* .(css|js|jpg)$ you're instructing NGINX to match requests asking for a file ending with .css, .js and .jpg.

In my applications, I usually store images in the WebP format even if the user submits a different format. This way, configuring the static cache becomes even easier for me.

You can use the add_header directive to include a header in the response to the client. Previously you've seen the proxy_set_header directive used for setting headers on an ongoing request to the backend server. The add_header directive on the other hand only adds a given header to the response.

By setting the Cache-Control header to public, you're telling the client that this content can be cached in any way. The Pragma header is just an older version of the Cache-Control header and does more or less the same thing.

The next header, Vary, is responsible for letting the client know that this cached content may vary.

The value of Accept-Encoding means that the content may vary depending on the content encoding accepted by the client. This will be clarified further in the next section.

Finally the expires directive allows you to set the Expires header conveniently. The expires directive takes the duration of time this cache will be valid. By setting it to 1M you're telling NGINX to cache the content for one month. You can also set this to 10m or 10 minutes, 24h or 24 hours, and so on.

Now to test out the configuration, sent a request for the the-nginx-handbook.jpg file from the server:

curl -I http://nginx-handbook.test/the-nginx-handbook.jpg

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sun, 25 Apr 2021 15:58:22 GMT
# Content-Type: image/jpeg
# Content-Length: 19209
# Last-Modified: Sun, 25 Apr 2021 08:35:33 GMT
# Connection: keep-alive
# ETag: "608529d5-4b09"
# Expires: Tue, 25 May 2021 15:58:22 GMT
# Cache-Control: max-age=2592000
# Cache-Control: public
# Pragma: public
# Vary: Accept-Encoding
# Accept-Ranges: bytes

As you can see, the headers have been added to the response and any modern browser should be able to interpret them.

How to Compress Responses

The final optimization technique that I'm going to show today is a pretty straightforward one: compressing responses to reduce their size.

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    include /env/nginx/mime.types;

    gzip on;
    gzip_comp_level 3;

    gzip_types text/css text/javascript;

    server {

        listen 80;
        server_name nginx-handbook.test;

        root /srv/nginx-handbook-demo/static-demo;

        location ~* \.(css|js|jpg)$ {
            access_log off;

            add_header Cache-Control public;
            add_header Pragma public;
            add_header Vary Accept-Encoding;
            expires 1M;
        }
    }
}

If you're not already familiar with it, GZIP is a popular file format used by applications for file compression and decompression. NGINX can utilize this format to compress responses using the gzip directives.

By writing gzip on in the http context, you're instructing NGINX to compress responses. The gzip_comp_level directive sets the level of compression. You can set it to a very high number, but that doesn't guarantee better compression. Setting a number between 1 - 4 gives you an efficient result. For example, I like setting it to 3.

By default, NGINX compresses HTML responses. To compress other file formats, you'll have to pass them as parameters to the gzip_types directive. By writing gzip_types text/css text/javascript; you're telling NGINX to compress any file with the mime types of text/css and text/javascript.

Configuring compression in NGINX is not enough. The client has to ask for the compressed response instead of the uncompressed responses. I hope you remember the add_header Vary Accept-Encoding; line in the previous section on caching. This header lets the client know that the response may vary based on what the client accepts.

As an example, if you want to request the uncompressed version of the mini.min.css file from the server, you may do something like this:

curl -I http://nginx-handbook.test/mini.min.css

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sun, 25 Apr 2021 16:30:32 GMT
# Content-Type: text/css
# Content-Length: 46887
# Last-Modified: Sun, 25 Apr 2021 08:35:33 GMT
# Connection: keep-alive
# ETag: "608529d5-b727"
# Expires: Tue, 25 May 2021 16:30:32 GMT
# Cache-Control: max-age=2592000
# Cache-Control: public
# Pragma: public
# Vary: Accept-Encoding
# Accept-Ranges: bytes

As you can see, there's nothing about compression. Now if you want to ask for the compressed version of the file, you'll have to send an additional header.

curl -I -H "Accept-Encoding: gzip" http://nginx-handbook.test/mini.min.css

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sun, 25 Apr 2021 16:31:38 GMT
# Content-Type: text/css
# Last-Modified: Sun, 25 Apr 2021 08:35:33 GMT
# Connection: keep-alive
# ETag: W/"608529d5-b727"
# Expires: Tue, 25 May 2021 16:31:38 GMT
# Cache-Control: max-age=2592000
# Cache-Control: public
# Pragma: public
# Vary: Accept-Encoding
# Content-Encoding: gzip

As you can see in the response headers, the Content-Encoding is now set to gzip meaning this is the compressed version of the file.

Now if you want to compare the difference in file size, you can do something like this:

cd ~
mkdir compression-test && cd compression-test

curl http://nginx-handbook.test/mini.min.css > uncompressed.css

curl -H "Accept-Encoding: gzip" http://nginx-handbook.test/mini.min.css > compressed.css

ls -lh

# -rw-rw-r-- 1 vagrant vagrant 9.1K Apr 25 16:35 compressed.css
# -rw-rw-r-- 1 vagrant vagrant  46K Apr 25 16:35 uncompressed.css

The uncompressed version of the file is 46K and the compressed version is 9.1K, almost six times smaller. On real life sites where stylesheets can be much larger, compression can make your responses smaller and faster.

How to Understand the Main Configuration File

I hope you remember the original nginx.conf file you renamed in an earlier section. According to the Debian wiki, this file is meant to be changed by the NGINX maintainers and not by server administrators, unless they know exactly what they're doing.

But throughout the entire article, I've taught you to configure your servers in this very file. In this section, however, I'll who you how you should configure your servers without changing the nginx.conf file.

To begin with, first delete or rename your modified nginx.conf file and bring back the original one:

sudo rm /etc/nginx/nginx.conf

sudo mv /etc/nginx/nginx.conf.backup /etc/nginx/nginx.conf

sudo nginx -s reload

Now NGINX should go back to its original state. Let's have a look at the content of this file once again by executing the sudo cat /etc/nginx/nginx.conf file:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 768;
    # multi_accept on;
}

http {

    ##
    # Basic Settings
    ##

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;
    # server_tokens off;

    # server_names_hash_bucket_size 64;
    # server_name_in_redirect off;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    ##
    # SSL Settings
    ##

    ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
    ssl_prefer_server_ciphers on;

    ##
    # Logging Settings
    ##

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    ##
    # Gzip Settings
    ##

    gzip on;

    # gzip_vary on;
    # gzip_proxied any;
    # gzip_comp_level 6;
    # gzip_buffers 16 8k;
    # gzip_http_version 1.1;
    # gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    ##
    # Virtual Host Configs
    ##

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}


#mail {
#    # See sample authentication script at:
#    # http://wiki.nginx.org/ImapAuthenticateWithApachePhpScript
# 
#    # auth_http localhost/auth.php;
#    # pop3_capabilities "TOP" "USER";
#    # imap_capabilities "IMAP4rev1" "UIDPLUS";
# 
#    server {
#        listen     localhost:110;
#        protocol   pop3;
#        proxy      on;
#    }
# 
#    server {
#        listen     localhost:143;
#        protocol   imap;
#        proxy      on;
#    }
#}

You should now be able to understand this file without much trouble. On the main context user www-data;, the worker_processes auto; lines should be easily recognizable to you.

The line pid /run/nginx.pid; sets the process ID for the NGINX process and include /etc/nginx/modules-enabled/*.conf; includes any configuration file found on the /etc/nginx/modules-enabled/ directory.

This directory is meant for NGINX dynamic modules. I haven't covered dynamic modules in this article so I'll skip that.

Now inside the the http context, under basic settings you can see some common optimization techniques applied. Here's what these techniques do:

• sendfile on; disables buffering for static files.
• tcp_nopush on; allows sending response header in one packet.
• tcp_nodelay on; disables Nagle's Algorithm resulting in faster static file delivery.

The keepalive_timeout directive indicates how long to keep a connection open and the types_hash_maxsize directive sets the size of the types hash map. It also includes the mime.types file by default.

I'll skip the SSL settings simply because we haven't covered them in this article. We've already discussed the logging and gzip settings. You may see some of the directives regarding gzip as commented. As long as you understand what you're doing, you may customize these settings.

You use the mail context to configure NGINX as a mail server. We've only talked about NGINX as a web server so far, so I'll skip this as well.

Now under the virtual hosts settings, you should see two lines as follows:

##
# Virtual Host Configs
##

include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;

These two lines instruct NGINX to include any configuration files found inside the /etc/nginx/conf.d/ and /etc/nginx/sites-enabled/ directories.

After seeing these two lines, people often take these two directories as the ideal place to put their configuration files, but that's not right.

There is another directory /etc/nginx/sites-available/ that's meant to store configuration files for your virtual hosts. The /etc/nginx/sites-enabled/ directory is meant for storing the symbolic links to the files from the /etc/nginx/sites-available/ directory.

In fact there is an example configuration:

ln -lh /etc/nginx/sites-enabled/

# lrwxrwxrwx 1 root root 34 Apr 25 08:33 default -> /etc/nginx/sites-available/default

As you can see, the directory contains a symbolic link to the /etc/nginx/sites-available/default file.

The idea is to write multiple virtual hosts inside the /etc/nginx/sites-available/ directory and make some of them active by symbolic linking them to the /etc/nginx/sites-enabled/ directory.

To demonstrate this concept, let's configure a simple static server. First, delete the default virtual host symbolic link, deactivating this configuration in the process:

sudo rm /etc/nginx/sites-enabled/default

ls -lh /etc/nginx/sites-enabled/

# lrwxrwxrwx 1 root root 41 Apr 25 18:01 nginx-handbook -> /etc/nginx/sites-available/nginx-handbook

Create a new file by executing sudo touch /etc/nginx/sites-available/nginx-handbook and put the following content in there:

server {
    listen 80;
    server_name nginx-handbook.test;

    root /srv/nginx-handbook-projects/static-demo;
}

Files inside the /etc/nginx/sites-available/ directory are meant to be included within the main http context so they should contain server blocks only.

Now create a symbolic link to this file inside the /etc/nginx/sites-enabled/ directory by executing the following command:

sudo ln -s /etc/nginx/sites-available/nginx-handbook /etc/nginx/sites-enabled/nginx-handbook

ls -lh /etc/nginx/sites-enabled/

# lrwxrwxrwx 1 root root 34 Apr 25 08:33 default -> /etc/nginx/sites-available/default
# lrwxrwxrwx 1 root root 41 Apr 25 18:01 nginx-handbook -> /etc/nginx/sites-available/nginx-handbook

Before validating and reloading the configuration file, you'll have to reopen the log files. Otherwise you may get a permission denied error. This happens because the process ID is different this time as a result of swapping the old nginx.conf file.

sudo rm /var/log/nginx/*.log

sudo touch /var/log/nginx/access.log /var/log/nginx/error.log

sudo nginx -s reopen

Finally, validate and reload the configuration file:

sudo nginx -t

# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

sudo nginx -s reload

Visit the server and you should be greeted with the good old The NGINX Handbook page:

If you've configured the server correctly and you're still getting the old NGINX welcome page, perform a hard refresh. The browser often holds on to old assets and requires a little cleanup.

How To Configure SSL and HTTP/2

HTTP/2 is the newest version of the wildly popular Hyper Text Transport Protocol. Based on Google's experimental SPDY protocol, HTTP/2 provides better performance by introducing features like full request and response multiplexing, better compression of header fields, server push and request prioritization.

Some of the notable features of HTTP/2 is as follows:

1. Binary Protocol - While HTTP/1.x was a text based protocol, HTTP/2 is a binary protocol resulting in less error during data transfer process.
2. Multiplexed Streams - All HTTP/2 connections are multiplexed streams meaning multiple files can be transferred in a single stream of binary data.
3. Compressed Header - HTTP/2 compresses header data in responses resulting in faster transfer of data.
4. Server Push - This capability allows the server to send linked resources to the client automatically, greatly reducing the number of requests to the server.
5. Stream Prioritization - HTTP/2 can prioritize data streams based on their type resulting in better bandwidth allocation where necessary.

If you want to learn more about the improvements in HTTP/2 this article by Kinsta may help.

While a significant upgrade over its predecessor, HTTP/2 is not as widely adapted as it should have been. In this section, I'll introduce you to some of the new features mentioned previously and I'll also show you how to enable HTTP/2 on your NGINX powered web server.

For this section, I'll be using the static-demo project. I'm assuming you've already cloned the repository inside /srv/nginx-handbook-projects directory. If you haven't, this is the time to do so. Also, this section has to be done on a virtual private server instead of a virtual machine.

For simplicity, I'll use the /etc/nginx/sites-available/default file as my configuration. Open the file using nano or vi if you fancy that.

nano /etc/nginx/sites-available/default

Update the file's content as follows:

server {
        listen 80;
        server_name nginx-handbook.farhan.dev;  

        root /srv/nginx-handbook-projects/static-demo;
}

As you can see, the /srv/nginx-handbook-projects/static-demo; directory has been set as the root of this site and nginx-handbook.farhan.dev has been set as the server name. If you do not have a custom domain set up, you can use your server's IP address as the server name here.

nginx -t

# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

nginx -s reload

Test the configuration by executing nginx -t and reload the configuration by executing nginx -s reload commands.

Finally visit your server and you should be greeted with a simple static HTML page.

One of the pre-requisite to have HTTP/2 working on your server is to have a valid SSL certificate. Lets do that first.

How To Configure SSL

For those of you who may not know, an SSL certificate is what allows a server to make the move from HTTP to HTTPS. These certificates are issued by a certificate authority (CA). Most of the authorities charge a fee for issuing certificates but nonprofit authorities such as Let's Encrypt, issues certificates for free.

If you want to understand the theory of SSL in a bit more detail, this article on the Cloudflare Learning Center may help.

Thanks to open-source tools like Certbot, installing a free certificate is dead easy. Head over to certbot.eff.org link. Now select the software and system that powers your server.

I'm running NGINX on Ubuntu 20.04 and if you've been in line with this article, you should have the same combination.

After selecting your combination of software and system, you'll be forwarded to a new page containing step by step instructions for installing certbot and a new SSL certificate.

The installation steps for certbot may differ from system to system but rest of the instructions should remain same. On Ubuntu, the recommended way is to use snap.

snap install --classic certbot

# certbot 1.14.0 from Certbot Project (certbot-eff✓) installed

certbot --version

# certbot 1.14.0

Certbot is now installed and ready to be used. Before you install a new certificate, make sure the NGINX configuration file contains all the necessary server names. Such as, if you want to install a new certificate for yourdomain.tld and www.yourdomain.tld, you'll have to include both of them in your configuration.

Once you're happy with your configuration, you can install a newly provisioned certificate for your server. To do so, execute the certbot program with --nginx option.

certbot --nginx

# Saving debug log to /var/log/letsencrypt/letsencrypt.log
# Plugins selected: Authenticator nginx, Installer nginx
# Enter email address (used for urgent renewal and security notices)
#  (Enter 'c' to cancel): shovik.is.here@gmail.com

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Please read the Terms of Service at
# https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
# agree in order to register with the ACME server. Do you agree?
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# (Y)es/(N)o: Y

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Would you be willing, once your first certificate is successfully issued, to
# share your email address with the Electronic Frontier Foundation, a founding
# partner of the Let's Encrypt project and the non-profit organization that
# develops Certbot? We'd like to send you email about our work encrypting the web,
# EFF news, campaigns, and ways to support digital freedom.
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# (Y)es/(N)o: N
# Account registered.

# Which names would you like to activate HTTPS for?
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# 1: nginx-handbook.farhan.dev
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Select the appropriate numbers separated by commas and/or spaces, or leave input
# blank to select all options shown (Enter 'c' to cancel): 
# Requesting a certificate for nginx-handbook.farhan.dev
# Performing the following challenges:
# http-01 challenge for nginx-handbook.farhan.dev
# Waiting for verification...
# Cleaning up challenges
# Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/default
# Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/default

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Congratulations! You have successfully enabled
# https://nginx-handbook.farhan.dev
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# IMPORTANT NOTES:
#  - Congratulations! Your certificate and chain have been saved at:
#    /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem
#    Your key file has been saved at:
#    /etc/letsencrypt/live/nginx-handbook.farhan.dev/privkey.pem
#    Your certificate will expire on 2021-07-30. To obtain a new or
#    tweaked version of this certificate in the future, simply run
#    certbot again with the "certonly" option. To non-interactively
#    renew *all* of your certificates, run "certbot renew"
#  - If you like Certbot, please consider supporting our work by:

#    Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
#    Donating to EFF:                    https://eff.org/donate-le

You'll be asked for an emergency contact email address, license agreement and if you would like to receive emails from them or not.

The certbot program will automatically read the server names from your configuration file and show you a list of them. If you have multiple virtual hosts on your server, certbot will recognize them as well.

Finally if the installation is successful, you'll be congratulated by the program. To verify if everything's working or not, visit your server with HTTPS this time:

As you can see, HTTPS has been enabled successfully and you can confirm that the certificate is verified by Let's Encrypt authority. Later on, if you add new virtual hosts to this server with new domains or sub domains, you'll have to reinstall the certificates.

It's also possible to install wildcard certificate such as *.yourdomain.tld for some supported DNS managers. Detailed instructions can be found on the previously shown installation instruction page.

A newly installed certificate will be valid for 90 days. After that, a renewal will be required. Certbot does the renewal automatically. You can execute certbot renew command with the --dry-run option to test out the auto renewal feature.

certbot renew --dry-run

# Saving debug log to /var/log/letsencrypt/letsencrypt.log

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Processing /etc/letsencrypt/renewal/nginx-handbook.farhan.dev.conf
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Cert not due for renewal, but simulating renewal for dry run
# Plugins selected: Authenticator nginx, Installer nginx
# Account registered.
# Simulating renewal of an existing certificate for nginx-handbook.farhan.dev
# Performing the following challenges:
# http-01 challenge for nginx-handbook.farhan.dev
# Waiting for verification...
# Cleaning up challenges

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# new certificate deployed with reload of nginx server; fullchain is
# /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Congratulations, all simulated renewals succeeded: 
#   /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem (success)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

The command will simulate a certificate renewal to test if it's correctly set up or not. If it succeeds you'll be congratulated by the program. This step ends the procedure of installing an SSL certificate on your server.

To understand what certbot did behind the scenes, open up the /etc/nginx/sites-available/default file once again and see how its content has been altered.

server {

    server_name nginx-handbook.farhan.dev;  

    root /srv/nginx-handbook-projects/static-demo;

    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/nginx-handbook.farhan.dev/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = nginx-handbook.farhan.dev) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    listen [::]:80;

    server_name nginx-handbook.farhan.dev;
    return 404; # managed by Certbot
}

As you can see, certbot has added quite a few lines here. I'll explain the notable ones.

server {
    # ...
    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    # ...
}

Like the 80 port, 443 is widely used for listening to HTTPS requests. By writing listen 443 ssl; certbot is instructing NGINX to listen for any HTTPS request on port 443. The listen [::]:443 ssl ipv6only=on; line is for handling IPV6 connections.

server {
    # ...
    ssl_certificate /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/nginx-handbook.farhan.dev/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
    # ...
}

The ssl_certificate directive is used for indicating the location of the certificate and the private key file on your server. The /etc/letsencrypt/options-ssl-nginx.conf; includes some common directives necessary for SSL.

Finally the ssl_dhparam indicates to the file defining how OpenSSL is going to perform Diffie–Hellman key exchange. If you want to learn more about the purpose of /etc/letsencrypt/ssl-dhparams.pem; file, this stack exchange thread may help you.

server {
    if ($host = nginx-handbook.farhan.dev) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    listen [::]:80;

    server_name nginx-handbook.farhan.dev;
    return 404; # managed by Certbot
}

This newly added server block is responsible for redirecting any HTTP requests to HTTPS disabling HTTP access completely.

How To Enable HTTP/2

Once you've successfully installed a valid SSL certificate on your server, you're ready to enable HTTP/2. SSL is a prerequisite for HTTP/2, so right off the bat you can see, security is not optional in HTTP/2.

HTTP/2 support for NGINX is provided by the ngx_http_v2_module module. Pre-built binaries of NGINX on most of the systems come with this module baked in. If you've built NGINX from source however, you'll have to include this module manually.

Before upgrading to HTTP/2, send a request to your server and see the current protocol version.

curl -I -L https://nginx-handbook.farhan.dev

# HTTP/1.1 200 OK
# Server: nginx/1.18.0 (Ubuntu)
# Date: Sat, 01 May 2021 10:46:36 GMT
# Content-Type: text/html
# Content-Length: 960
# Last-Modified: Fri, 30 Apr 2021 20:14:48 GMT
# Connection: keep-alive
# ETag: "608c6538-3c0"
# Accept-Ranges: bytes

As you can see, by default the server is on HTTP/1.1 protocol. On the next step, we'll update the configuration file as necessary for enabling HTTP/2.

To enable HTTP/2 on your server, open the /etc/nginx/sites-available/default file once again. Find wherever it says listen [::]:443 ssl ipv6only=on; or listen 443 ssl; and update them to listen [::]:443 ssl http2 ipv6only=on; and listen 443 ssl http2; respectively.

server {

    server_name nginx-handbook.farhan.dev;  

    root /srv/nginx-handbook-projects/static-demo;

    listen [::]:443 ssl http2 ipv6only=on; # managed by Certbot
    listen 443 ssl http2; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/nginx-handbook.farhan.dev/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = nginx-handbook.farhan.dev) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    listen [::]:80;

    server_name nginx-handbook.farhan.dev;
    return 404; # managed by Certbot
}

Test the configuration file by executing niginx -t and reload the configuration by executing nginx -s reload commands. Now send a request to your server again.

curl -I -L https://nginx-handbook.farhan.dev

# HTTP/2 200 
# server: nginx/1.18.0 (Ubuntu)
# date: Sat, 01 May 2021 09:03:10 GMT
# content-type: text/html
# content-length: 960
# last-modified: Fri, 30 Apr 2021 20:14:48 GMT
# etag: "608c6538-3c0"
# accept-ranges: bytes

As you can see, HTTP/2 has been enabled for any client supporting the new protocol.

How to Enable Server Push

Server push is one of the many features that HTTP/2 brings to the table. Which means the server can push files to the client without the client having to request for them. In a HTTP/1.x server, a typical request for static content may look like as follows:

But on a server push enabled HTTP/2 server, it may look like as follows:

On a single request for the index.html file the server responds with the style.css file as well, minimizing the number of requests in the process.

In this section, I'll use an open-source HTTP client named Nghttp2 for testing the server.

apt install nghttp2-client -y

# Reading package lists... Done
# Building dependency tree       
# Reading state information... Done
# The following additional packages will be installed:
#   libev4 libjansson4 libjemalloc2
# The following NEW packages will be installed:
#   libev4 libjansson4 libjemalloc2 nghttp2-client
# 0 upgraded, 4 newly installed, 0 to remove and 0 not upgraded.
# Need to get 447 kB of archives.
# After this operation, 1,520 kB of additional disk space will be used.
# Get:1 http://archive.ubuntu.com/ubuntu focal/main amd64 libjansson4 amd64 2.12-1build1 [28.9 kB]
# Get:2 http://archive.ubuntu.com/ubuntu focal/universe amd64 libjemalloc2 amd64 5.2.1-1ubuntu1 [235 kB]
# Get:3 http://archive.ubuntu.com/ubuntu focal/universe amd64 libev4 amd64 1:4.31-1 [31.2 kB]
# Get:4 http://archive.ubuntu.com/ubuntu focal/universe amd64 nghttp2-client amd64 1.40.0-1build1 [152 kB]
# Fetched 447 kB in 1s (359 kB/s)     
# Selecting previously unselected package libjansson4:amd64.
# (Reading database ... 107613 files and directories currently installed.)
# Preparing to unpack .../libjansson4_2.12-1build1_amd64.deb ...
# Unpacking libjansson4:amd64 (2.12-1build1) ...
# Selecting previously unselected package libjemalloc2:amd64.
# Preparing to unpack .../libjemalloc2_5.2.1-1ubuntu1_amd64.deb ...
# Unpacking libjemalloc2:amd64 (5.2.1-1ubuntu1) ...
# Selecting previously unselected package libev4:amd64.
# Preparing to unpack .../libev4_1%3a4.31-1_amd64.deb ...
# Unpacking libev4:amd64 (1:4.31-1) ...
# Selecting previously unselected package nghttp2-client.
# Preparing to unpack .../nghttp2-client_1.40.0-1build1_amd64.deb ...
# Unpacking nghttp2-client (1.40.0-1build1) ...
# Setting up libev4:amd64 (1:4.31-1) ...
# Setting up libjemalloc2:amd64 (5.2.1-1ubuntu1) ...
# Setting up libjansson4:amd64 (2.12-1build1) ...
# Setting up nghttp2-client (1.40.0-1build1) ...
# Processing triggers for man-db (2.9.1-1) ...
# Processing triggers for libc-bin (2.31-0ubuntu9.2) ...

nghttp --version

# nghttp nghttp2/1.40.0

Lets test by sending a request to the server without server push.

nghttp --null-out --stat https://nginx-handbook.farhan.dev/index.html

# id  responseEnd requestStart  process code size request path
#  13      +836us       +194us    642us  200  492 /index.html

nghttp --null-out --stat --get-assets https://nginx-handbook.farhan.dev/index.html

# id  responseEnd requestStart  process code size request path
#  13      +836us       +194us    642us  200  492 /index.html
#  15     +3.11ms      +2.65ms    457us  200  45K /mini.min.css
#  17     +3.23ms      +2.65ms    578us  200  18K /the-nginx-handbook.jpg

On the first request --null-out means discard downloaded data and --stat means print statistics on terminal. On the second request --get-assets means also download assets such as stylesheets, images and scripts linked to this files. As a result you can tell by the requestStart times, the css file and image was downloaded shortly after the html file was downloaded.

Now, lets enable server push for stylesheets and images. Open /etc/nginx/sites-available/default file and update its content as follows:

server {

    server_name nginx-handbook.farhan.dev;

    root /srv/nginx-handbook-projects/static-demo;

    listen [::]:443 ssl http2 ipv6only=on; # managed by Certbot
    listen 443 ssl http2; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/nginx-handbook.farhan.dev/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/nginx-handbook.farhan.dev/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    location = /index.html {
        http2_push /mini.min.css;
        http2_push /the-nginx-handbook.jpg;
    }

    location = /about.html {
        http2_push /mini.min.css;
        http2_push /the-nginx-handbook.jpg;
    }

}
server {
    if ($host = nginx-handbook.farhan.dev) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    listen 80;
    listen [::]:80;

    server_name nginx-handbook.farhan.dev;
    return 404; # managed by Certbot
}

Two location blocks have been added to exactly match /index.html and /about.html locations. The http2_push directive is used for sending back additional response. Now whenever NGINX receives a request for one of these two locations, it'll automatically send back the css and image file.

Test the configuration by executing nginx -t and reload the configuration by executing nginx -s reload commands.

nginx -t

# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

nginx -s reload

Now send another request to the server using nghttp and do not include --get-assets option.

nghttp --null-out --stat https://nginx-handbook.farhan.dev/index.html

# id  responseEnd requestStart  process code size request path
#  13     +1.49ms       +254us   1.23ms  200  492 /index.html
#   2     +1.56ms *    +1.35ms    212us  200  45K /mini.min.css
#   4     +1.71ms *    +1.39ms    318us  200  18K /the-nginx-handbook.jpg

As you can see, although the assets were not requested, the server has sent them to the client. Looking at the time measurements, process time has gone down and the three responses ended almost simultaneously.

This was a very simple example of server push but depending on the necessities of your project, this configuration can become much complex. This article by Owen Garrett on the official NGINX blog can help you with more complex server push configuration.

Conclusion

I would like to thank you from the bottom of my heart for the time you've spent on reading this article. I hope you've enjoyed your time and have learned all the essentials of NGINX.

Apart from this one, I've written full-length handbooks on other complicated topics available for free on freeCodeCamp.

These handbooks are part of my mission to simplify hard to understand technologies for everyone. Each of these handbooks takes a lot of time and effort to write.

If you've enjoyed my writing and want to keep me motivated, consider leaving starts on GitHub and endorse me for relevant skills on LinkedIn. I also accept sponsorship so you may consider buying me a coffee if you want to.

I'm always open to suggestions and discussions on Twitter or LinkedIn. Hit me with direct messages.

In the end, consider sharing the resources with others, because

Sharing knowledge is the most fundamental act of friendship. Because it is a way you can give something without loosing something. — Richard Stallman

Till the next one, stay safe and keep learning.

You can find the code and video in the summary at the end.

What You'll Learn in This Article

In every project lifecycle, the time comes to publish it, and it is not always that obvious how to do so. The production environment is different than the development one, and users will not take any extra steps to run it. Most web apps consume some sort of APIs, and often, they are hosted on a different server.

In this case, as a developer, we need to solve Cross-Origin Resource Sharing (CORS) issues. Too often, we end up building a backend even though it is not necessary. I believe that developers should keep their applications simple, and cut out all redundant pieces.

In this article, I would like to show you how I prepare my React apps to deploy them to production.

I could build a trivial React example app but it wouldn't be very helpful. So I decided to hook my app into a real API provided by FED St. Louis. The API requires an access key to retrieve data, and endpoints are protected against cross domain requests — no external web app will be able to directly consume data.

Take note: If you application relies on server-side rendering this is not the right deployment strategy. You can get inspired but you will still need some sort of backend.

Prerequisites

It is critical to have some basic knowledge of how to build React apps. You should also know some Docker fundamentals before you follow the instructions in this article.

If you miss anything, don't worry! Just check out this amazing article and YouTube tutorial on FreeCodeCamp:

• A Beginner-Friendly Introduction to Containers, VMs and Docker by @iam_preethi
• Create React App Crash Course

How to Build an Example React App

I bootstrapped a simple web app using create-react-app. The only job the app has is displaying a line chart with a representation of the GDP of the United States.

The app retrieves data only from the following API:

https://api.stlouisfed.org/fred/series/observations?series_id=GDPCA&frequency=a&observation_start=1999-04-15&observation_end=2021-01-01&file_type=json&api_key=abcdefghijklmnopqrstuvwxyz123456

Here are the parameters:

• series_id - The id for a series. The GDPCA stands for the "Real GDP".
• frequency - The aggregation of the data. The a stands for annual.
• observation_start - The start of the observation period.
• observation_end - The end of the observation period.
• file_type - The format of the data. Default is xml.
• api_key - The access key required to retrieve any data from this API. You can request one here.

You can find more details in the documentation.

Life isn't always perfect, and the API design is not ideal. It requires the developer to pass the access key and expected output of the data as URL parameters.

Passing the output as a parameter is not a problem for us because it only adds some noise - but the leaking API key is. Imagine if somebody intercepts them and abuses the API to perform some prohibited action. We don't want to risk it.

Let's assume for a moment that the API keys are not a problem. Still, it isn't possible to take advantage of this API. The FRED API is protected against cross-domain requests so that we will get the following errors if we try to call it from an external domain:

Many developers would suggest building middleware (a backend) to proxy requests to the API and filter sensitive data. They would say they might need to add new features in the future, and to a certain degree, it is a fair approach.

But I prefer to build my apps in a more YAGNI way (You Ain't Gonna Need It). So that I'm going to avoid build the backend until it is necessary - in our case I will not build it at all.

Let's use NGINX!

I am a big fan of NGINX because it brings simplicity with it. NGINX has all you need to prepare a production-grade web server such as HTTP2, compression, TLS, and many other features.

The most important thing is that we can achieve all this by defining a few lines of configuration. Just take a look at the snippet below:

...

http {
    ...

    server {
        ...

        location /api {
            set         $args   $args&&file_type=json&api_key=abcdefghijklmnopqrstuvwxyz123456;
            proxy_pass  https://api.stlouisfed.org/fred/series;
        }
    }
}

Those 4 lines are all I needed to hide our API key and suppress the CORS errors. Literally! From now on, all HTTP requests to /api will be proxied to FRED API, and only our apps will be able to consume the API. All external requests will face CORS errors.

To get rid of clutter, I replaced all default content of the file with ... (three dots). You can find the full version on my GitHub or video (links below).

And this is how our endpoint looks:

/api/observations?series_id=GDPCA&frequency=a&observation_start=1999-04-15&observation_end=2021-01-01

We need to pass neither the api_key nor file_type parameters to retrieve data. And nobody can read the access key from the URL, so it is safe.

Docker loves NGINX

The most convenient way to run NGINX in the cloud is to use Docker. For this part, I assume that you know what Docker is (but if not please read the article linked in the prerequisites).

We just need to create a Dockerfile with the following contents:

FROM nginx

COPY container /
COPY build /usr/share/nginx/html

And now, only three more steps are needed to run the FRED APP:

1. Build the React application. This process generates the build/ directory containing static files.
2. Build the Docker image. It will create a runnable Docker image.
3. Publish the Docker image to some repository or run it on the local machine.

For now, let's try to run it on our machine.

$ yarn install
$ yarn build
$ docker build -t msokola/fred-app:latest .
$ docker run -p 8081:80 -it msokola/fred-app:latest

The 8081 is a port on your machine. It means the app will be available under the following URL: http://localhost:8081.

After opening this URL in the browser you should see logs like this in your terminal:

0.0.0.1 - - [11/Mar/2021:18:57:50 +0000] "GET / HTTP/1.1" 200 1556 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.192 Safari/537.36" "-"
...
0.0.0.1 - - [11/Mar/2021:18:57:51 +0000] "GET /api/observations?series_id=GDPCA&frequency=a&observation_start=1999-04-15&observation_end=2021-01-01 HTTP/1.1" 200 404 "http://localhost:8081/" "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.192 Safari/537.36" "-"

Pay attention to those 200s as they stand for HTTP status OK. If you see a 400 next to the API request it means something is wrong with your API key. The 304 is also fine (it means the data was cached).

How to Deploy the Container on AWS

The container is working, so we can deploy it. In this part of the article, I am going to show you how to run your application in Amazon Web Services (AWS).

AWS is one of the most popular cloud platforms. If you want to use Microsoft Azure or any other platform, the steps will be similar but the syntax of the commands will differ.

Take note: I recorded a YouTube video so you can watch me going through the complete deployment process. If you get stuck or encounter any issues, you can check if we have the same results at each step. If you want to watch the video, click here or you can find it embedded in the Summary below.

1. Install AWS CLI tools

Before we get started you will need to install the AWS CLI tools, so you can invoke commands on your cloud.

AWS offers installation wizards for all operating systems, so I am going to skip this section. After a successful installation you have to login by typing the following command:

$ aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-2
Default output format [None]: json

To generate access keys, you need to log in to your AWS Console. There, click on your username, and select "My Security Credentials".

2. Create a new Elastic Container Registry (ECR)

Once the CLI tools are set up, we will need to create a space where we can store the executables of our application. We use Docker, so our executables will be Docker images which we will run on virtual machines.

AWS offers a dedicated service for storing images called the Elastic Container Registry. The following command will create one for us:

aws ecr create-repository --repository-name react-to-aws --region us-east-2

Here are the parameters:

• ecr - The acronyms of "Elastic Container Registry".
• repository-name - The name of our registry. Please have in mind we will be referring to this name later.
• region - The region code. You can find a region closest to your location to reduce latency. Here's a list of all regions.

You can find more details in the documentation.

And here's the expected output:

{
    "repository": {
        "repositoryArn": "arn:aws:ecr:us-east-2:1234567890:repository/react-to-aws2",
        "registryId": "1234567890",
        "repositoryName": "react-to-aws",
        "repositoryUri": "1234567890.dkr.ecr.us-east-2.amazonaws.com/react-to-aws2",
        "createdAt": "2021-03-16T22:50:23+04:00",
        "imageTagMutability": "MUTABLE",
        "imageScanningConfiguration": {
            "scanOnPush": false
        },
        "encryptionConfiguration": {
            "encryptionType": "AES256"
        }
    }
}

3. Push Docker Images to the Cloud

In this step, we are going to push our Docker images into the cloud. We can do it by copying the push commands from our AWS Console.

Let's open AWS Console in the browser, and click on Elastic Container Registry from the "All Services - Containers" list. If you didn't change your region you can just click here. You are going to see the full list of your repositories:

Now you need to select the react-to-aws repository, and then "View push commands" from the menu (marked with red circles in the image above). You are going to see the following window:

You need to copy all commands from the modal into your terminal. Do not copy commands from the snippet below because it won't work.

$ aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-2.amazonaws.com
Login Succeeded

$ docker build -t react-to-aws .
[+] Building 0.6s (8/8) FINISHED
...

$ docker tag react-to-aws:latest 123465789.dkr.ecr.us-east-2.amazonaws.com/react-to-aws:latest

$ docker push 123456789.dkr.ecr.us-east-2.amazonaws.com/react-to-aws:latest
The push refers to repository [123456789.dkr.ecr.us-east-2.amazonaws.com/react-to-aws:latest]
...
latest: digest: sha256:3921262a91fd85d2fccab1d7dbe7adcff84f405a3dd9c0e510a20d744e6c3f74 size: 1988

Now you can close the modal, and click on the name of the repository (react-to-aws) to browse the list of available images. You should see the following screen:

Your application is in the repository, ready for deployment! Now click on "Copy URI" and keep the content of your clipboard (paste it in some notepad or text file), as we will need to run it!

4. Configure the Application

Our image is available in the cloud, so now we need to configure it.

Virtual machines don't know how to execute your image to ensure it works well. We must define some instructions such as open ports, environment variables, and so on. AWS calls it task definition.

Open AWS Console, and click on Elastic Container Service (ECS) from the "All Services - Containers" list. If you didn't change your region you can click here.

Now select Task Definitions, and click on "Create new Task Definition" as marked in the image below:

We have two options for running our task: FARGATE and EC2. Choose FARGATE, and click "Next step".

In the next step, you need to fill out the form with the following values:

• Task Definition Name - react-to-aws-task.
• Task Role - none.
• Task memory (GB) - 0.5GB (the smallest).
• Task CPU (vCPU) - 0.25 vCPU (the smallest).

Once you've reached the "Container Definitions" section click "Add container":

Fill out the form with the following values:

• Container Name - react-to-aws.
• Image - The URI from the step 4. You've pasted it somewhere.
• Memory Limits (MiB)- Soft limit 128.
• Port mappings - 80 - the HTTP port.

Other options aren't relevant for us. Now click on the "Add" button to add a container, and finish the task definition by clicking Create. You should see the following screen, and click on "View task definition".

5. Let's run it!

Finally, we can create a cluster, so we can run our application in the cloud. You need to select "Clusters" from the menu on the left-hand side, and "Create Cluster". As shown in the image below:

Now we have three options: Networking only, EC2 Linux + Networking, and EC2 Windows + Networking. Choose the first one - Networking only, and click on "Next step". You should see the following screen:

Enter the cluster name react-to-aws, and click on the "Create" button. You should see a successful lunch status. It looks similar to the screen we got once our task definition was created. Now click on "View Cluster".

Now you need to click on the "Tasks" tab, and click on "Run new Task". Congratulations! You have reached the very last form to fill out :)

Fill out the form with the following values:

• Launch type - FARGATE.
• Cluster VPC - The first one.
• Subnet - The first one.

Keep the other values as they are, and click the "Run task" button. You should see the following screen:

We will need to wait about a minute until the "Last status" changes into RUNNING. Please have in mind that you need to click the "Refresh" button to refresh the list. Once the task status is running, click on the task name.

In the "Network" section you will find the Public IP of your container. You can open it in your browser, and you will see your application.

Summary

If you're at the beginning of your career, you might not have ever deployed an application yourself. But it is good to learn that skill, because one day you will need to do so.

Every project needs to face users otherwise it will have no chance of being successful, and will never pay for itself.

“A ship in harbor is safe — but that is not what ships are built for.”
— John A. Shedd

The configuration process is a bit tedious, but the good news is that you need to do it only once.

After you configure everything, your next deployments will be simpler. You only need to push the new image and restart the task to deploy a new version of your application.

If you are interested in digging deeper into AWS, FreeCodeCamp offers a free tutorial on it (~5 hours).

You can find a screencast of this tutorial (17 minutes) on my YouTube channel. I am at the very beginning of my YouTube journey - at least weekly I upload a video on programming. It would mean the world to me if you watch my screencast, subscribe, and hit the like button :)

You can find all the code in this GitHub repository : https://github.com/mateuszsokola/react-to-aws

You can DM me on Twitter: @msokola

That is all folks! I hope you liked it and have a great day :)

_Photo by [Unsplash](https://unsplash.com/@vidarnm?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Vidar Nordli-Mathisen on <a href="https://www.freecodecamp.org/news/s/photos/ship-storm?utm_source=unsplash&utm_medium=referral&utmcontent=creditCopyText)

In this tutorial, we are going to learn everything we need to know before deploying a Node app to a production server.

We will start by renting a server on Digital Ocean. Then we'll configure this server, connect to it, install Nginx and configure it, pull or create our Node app, and run it as a process.

As you can see, there is a lot to do and it will be an action-packed tutorial. So let's get started without wasting any time.

You should have some basic knowledge on how the Terminal works and how to work in Vi/Vim before getting started. If you are not familiar with basic commands, I would advise you to read up on them a bit.

I will run the commands in MacOS. If you want to follow this tutorial in Windows, you can use Powershell or some other Unix emulator of your choice.

Although I will use Node.js as the platform of our example application, most of the steps are the same for any web application.

Why Digital Ocean?

I choose Digital Ocean because it is cheap and the interface is really easy to use, compared to the likes of AWS. Also, a $100 credit is included in the GitHub student pack so you do not have to pay anything for a couple of months. It is ideal for deploying a course or hobby project.

It has a concept called Droplets, which is basically your share of a server. You can think of the server as an apartment in which you own or rent a flat.

Droplets work with the help of Virtual Machines which run on the server. So a Droplet is your Virtual Machine on a shared server. Since it is a VM, its CPU and memory share can be easily increased, usually by throwing more money at your provider.

How to Create a Digital Ocean Project

I am assuming that you have already signed up and logged in to Digital Ocean before proceeding. We should first create a project that will contain our droplets. Let's click on the new project button on the left side menu. It will ask you to name your project.

Enter whatever name you want. It will also ask you if you want to move any resources, but for now just click Skip – we will create the droplet later.

How to Create a Droplet on Digital Ocean

Let's create our droplet by clicking the Get Started button.

After clicking the button, it will ask us to choose a VM image.

Choosing an Image

On this page, I will select Ubuntu 20.04 since it is the latest LTS version at the time I am writing this post. LTS means "Long Term Support". It is best to go with the LTS version for actual projects, because the provider guarantees that it will be supported and maintained for a long time. This means you will not have problems in the long run.

I have chosen Ubuntu, and would recommend it to you since it is the most commonly used Linux distribution. This means it's also the easiest to find answers to your future questions.

You can also choose to have a Dedicated CPU if you need it. If you are building your own startup or any business project, I would recommend reading this post which contains detailed instructions about how to pick the right option for you.

I will go with the cheapest option in this case.

Then you will need to select a Datacenter region. You should pick the one that is closest to you to minimize network delay.

Select a Datacenter

Next let's select SSH Keys as the Authentication Method, since it is much more secure than basic password authentication.

Authentication Method

To connect to the server we need to generate a new SSH key on our own device and add it to Digital Ocean.

How to Generate an SSH Key

I will generate the key on my macOS device. If you are using Windows you can refer to this article. Open your terminal and move into the ssh folder:

cd ~/.ssh

Then create your SSH key:

ssh-keygen

If your computer says that it does not know this command, you should install it via brew.

It will ask you to name the file and enter a passphrase. Do not enter a name, just press enter and go with the defaults. You should have these files generated. I have named mine digital-ocean-ssh in this screenshot, so do not get confused by that.

❯ lsid_dsa      id_rsa      known_hosts

Our public key is the id_dsa and the id_rsa is our private key. If you forget which one is private, you can always print one of them to see.

How to Add Your SSH Key to Digital Ocean

Now we want to copy our public key and upload it to Digital Ocean so they will know which key to use in authentication.

Copy this whole key including the ssh-rsa part.

Click on "New SSH Key":

Paste the key in the textbox that appears after you click the button and you should see your SSH key.

How to Connect to the Server

We will use the terminal to connect to our server with SSH. You can also take a look at Termius for a nice interface if you want.

Run this command in your terminal after replacing the IP_ADDRESS with your server's IP address (you can look it up from Digital Ocean's panel).

ssh root@IP_ADDRESS

If everything goes well, now you should be in the server's terminal. We have successfully connected to server. If there is any error, you can debug it by running the command with the "-v" option or "-vv" for even more verbosity.

How to Set Up the Server

We need to do some initial setup before deploying the Node app to the server.

Update and Upgrade Software

We want to update the server's software to make sure we are using the latest versions.

Many servers are vulnerable to attacks because they are using older versions of software with known vulnerabilities. Attackers can search for the vulnerabilities in those software and try to exploit them in order to gain access to your server.

You can update Ubuntu's software using the "apt update" command.

apt updateHit:1 https://repos.insights.digitalocean.com/apt/do-agent main InReleaseGet:2 http://mirrors.digitalocean.com/ubuntu focal InRelease [265 kB]      Hit:3 http://mirrors.digitalocean.com/ubuntu focal-updates InRelease                Get:4 http://security.ubuntu.com/ubuntu focal-security InRelease [109 kB]Hit:5 http://mirrors.digitalocean.com/ubuntu focal-backports InReleaseFetched 374 kB in 1s (662 kB/s)                          Reading package lists... DoneBuilding dependency tree       Reading state information... Done96 packages can be upgraded. Run 'apt list --upgradable' to see them.

If you read the message, it says that "96 packages can be upgraded". We have installed the new software packages but we have not upgraded our software to those versions yet.

To do that, let's run another command:

apt upgrade

Type y when it prompts you and it will upgrade the software.

Create a User

We have connected to the server as the root user (the user with the highest privileges). Being the root is dangerous and can open us up to vulnerabilities.

Therefore we should create a new user and not run commands as root. Replace $username with a username of your choice.

whoamiroot

adduser $username

You need to enter a password for the user. After that point, it will ask a bunch of questions, so just input y until the prompting is over.

The new user has been created but we also need to add this new user to the "sudo" group so that we can perform any action we need.

usermod -aG sudo $USERNAME

We add group with the -aG (add group) option, and we add the group name sudo to our username.

We are still root, so let's switch our user to the newly created user, using the su (switch user) command.

su $USERNAME

After this point, if you run whoami command, you should see your username. You can confirm the existence of the sudo group by running this command:

sudo cat /var/log/auth.log

Only superusers can view this file and OS will ask for your user password after you run this command.

Copy the SSH Key

We have successfully created the user but we have not enabled SSH login for this new user yet.

Therefore, we have to copy the public key that we previously created on our local computer and paste it into this user's SSH folder so SSH can know which key should it use to authenticate our new user.

mkdir -p ~/.ssh

The -p argument creates the directory if it does not exist.

vi ~/.ssh/authorized_keys

We will use vi or vim to create a file and call it authorized_keys.

Copy your public key (id_dsa file) then press "i" to go into insert mode. Then just paste it into this file with CMD + V.

Press esc to quit insert mode, type :wq to save and quit.

If you have any problems about using Vim-Vi, you can check out one of the many tutorials that explain how to use it.

Connect to Server as New User

Now we should be able to connect to the server without any problems using ssh. You can use this command to connect, just remember to insert your username and IP_ADDRESS.

ssh $USERNAME@IP_ADDRESS

If you are having any problems at this point, you should just delete the droplet and start over. It does not take a lot of time to start over but debugging server problems can be difficult.

How to Disable Root Login

It is a good practice to disable Root login as a security precaution, so let's do that now.

It can be useful to change the file permission just in case so that we won't run into problems regarding permissions in the future.

chmod 644 ~/.ssh/authorized_keys

Let's now open our sshd_config file:

sudo vi /etc/ssh/sshd_config

Find this line and change the yes to no in the same way we did earlier with vi.

PermitRootLogin no

Save and quit vi.

How to Install Node.js and Git

We can now go ahead and install Node.js and Git:

sudo apt install nodejs npm

sudo apt install git

We are now ready to create a Node app and run it. You can either pull your Node project from Github or create a Node app here just to test if it works.

Move to a directory of your choice and create an "app.js" file:

sudo vi app.js

You can paste the following snippet into your app.js file:

const express = require('express');const app = express();const port = 3000;app.get('/', (req, res) => {        res.send('Hello World');});app.listen(port, () => console.log(`Example app listening on port ${port}!`));

Now we can run it with the command:

node app.js

You should see "Example app listening on port 3000!" on your terminal.

We can confirm that it is working by sending a request to our server:

GET http://IP_ADDRESS:3000/

Send this request either from an HTTP client like Postman or your browser and you should see the "Hello World" message.

At this point, you should notice that something is wrong: Regular users do not know how to send requests to port 3000.

We should redirect the requests that come to our web server from our IP to port 3000. We can accomplish this with the help of Nginx.

How to Install and Configure Nginx

We will use Nginx as a Reverse Proxy to redirect the requests to our Node app.

Nginx as a Reverse Proxy

Let's install Nginx:

sudo apt install nginx

Start the Nginx service:

sudo service nginx start

We can test to see if it is working by sending a request to our server's IP address from the browser. Type your server's IP address to your browser and you should see this:

It is important to know that Nginx serves from "/var/www/html" by default and you can find this HTML file in that directory as well.

I also advise you to create a folder under "/var/www", call it app, and move your Node app to that folder so it will be easy to find.

How to Configure the Nginx Reverse Proxy

We will edit the Nginx config file to configure a reverse proxy:

sudo vi /etc/nginx/sites-available/default

In this file you need to find the location / block and change it as follows:

location / {                # First attempt to serve request as file, then                # as directory, then fall back to displaying a 404.                proxy_pass http://127.0.0.1:3000/;        }

The proxy_pass directive proxies the request to a specified port. We give the port that our Node application is running on.

Let's restart Nginx so the changes can take effect:

sudo service nginx reload

After this step, we should be able to see the message when we send a request to our server. Congratulations, we have completed the minimum number of steps to deploy a Node app!

But I still advise you to complete the following bonus step as well, as I believe it's quite important.

If you can't see the hello world message, you can check if your app and Nginx are running and restart them.

How to Run your App as a Process

We do not want to start our application manually every time something goes wrong and our app crashes. We want it to restart on its own. Also, whenever the server starts, our app should start too.

To make this happen, we can use PM2. Let's install PM2 and configure it.

sudo npm i -g pm2

We are installing pm2 globally by using the "-g" option so that it will be accessible from every folder.

pm2 start app.js

This makes sure that the app will restart if it exits due to an error.

Let's save the current process list.

pm2 save

We also need to convert it to a daemon that runs whenever the system starts:

pm2 startup systemd

As a reminder, in this tutorial, I'm using the commands for Ubuntu. If you are using any other Linux distro, you should replace systemd in this command.

We can confirm that the service is getting restarted by rebooting the server and sending a request without running app.js by hand:

sudo reboot

After sending a request as we did earlier, you should be able to see the hello world message.

Conclusion

In this tutorial we started from scratch, rented a server for ourselves, connected to it, and configured it in a way that it serves our Node.js app from port 80.

If you have followed along and were able to complete all steps, congratulations! You can be proud of yourself, as this was not the easiest topic :). I hope that you have learned a lot. Thank you for your time.

I am planning to explore this topic further by connecting the server to a domain name, then connecting it to CircleCI for continuous integration. I'll also go through the required steps to make your Node.js/React app production ready. This post had already gotten long enough, though, so those topics are reserved for another post :)

If you have enjoyed reading and want to get informed about my future posts, you can subscribe to my personal blog. You can see my previous posts there if you are interested in reading more. I usually write about web development-related topics.

As the creator of Foo, a platform for website quality monitoring, I recently endeavored in a migration to Kubernetes and EKS (an AWS service).

Kubernetes provides a robust level of DNS support. Luckily for us, within a cluster, we can reference pods by host name as defined in a spec.

But what if we want to expose an app to the outside world as a website under a static domain? I thought this would be a common, well documented case, but boy was I wrong.

Assume a Service named foo in the Kubernetes namespace bar. A Pod running in namespace bar can look up this service by simply doing a DNS query for foo. A Pod running in namespace quux can look up this service by doing a DNS query for foo.bar ~ DNS for Services and Pods - Kubernetes

Yes, that's great ❤️ But this still leads to many unsolved mysteries. Let's take this one step at a time shall we?! This post will address the following items.

1. How to define services
2. How to expose multiple services under one NGINX server. No fancy schmancy "Ingress" needed ?
3. How to create an external DNS and connect to a domain you've acquired through any qualified registry like GoDaddy or Google Domains, for example. We'll use Route 53 and ExternalDNS to do the heavy lifting.

This post assumes a setup with EKS and eksctl as documented in "Getting started with eksctl", but many of the concepts and examples in this post could be applicable in a variety of configurations.

Step 1: Define Services

Connecting Applications with Services explains how to expose an NGINX application by defining a Deployment and Service. Let's go ahead and create 3 applications in the same manner: a user facing web app, an API and a reverse proxy NGINX server to expose the two apps under one host.

web-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: web
        # etc, etc

web-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: web
  labels:
    app: web
spec:
  ports:
  - name: "3000"
    port: 3000
    targetPort: 3000
  selector:
    app: web

api-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
      - name: api
        # etc, etc

api-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: api
  labels:
    app: api
spec:
  ports:
  - name: "3000"
    port: 3000
    targetPort: 3000
  selector:
    app: api

Fair enough, let's move on!

Step 2: Expose Multiple Services Under One NGINX Server

NGINX is a reverse proxy in that it proxies a request by sending it to a specified origin, fetches the response, and sends it back to the client.

Going back to the bit about service names being accessible to other pods in a cluster, we can setup an NGINX configuration to look something like this.

sites-enabled/www.example.com.conf

upstream api {
  server api:3000;
}

upstream web {
  server web:3000;
}

server {
  listen 80;

  server_name www.example.com;

  location / {
    proxy_pass http://web;
  }

  location /api {
    proxy_pass http://api;
  }
}

Note how we can reference origin hosts like web:3000 and api:300. Niiiice!

nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        ports:
        - containerPort: 80

nginx-service.yaml

apiVersion: v1
kind: Service
metadata:
  name: nginx
  annotations:
    # this part will make more sense later
    external-dns.alpha.kubernetes.io/hostname: www.example.com
  labels:
    app: nginx
spec:
  type: LoadBalancer
  ports:
  - name: "80"
    port: 80
    targetPort: 80
  selector:
    app: nginx

...and, we're done! Right? In my experience, initially I thought so. The [LoadBalancer](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) provides an externally-accessible IP. You can confirm by running kubectl get svc and sure enough you'll find a host name listed in the EXTERNAL-IP column.

Assuming you've acquired a domain from a provider that offers an interface to manage DNS settings, you could simply add this URL as a CNAME and you're good, right? Well, kinda... but not so much.

Kubernetes Pods are considered to be relatively ephemeral (rather than durable) entities. Find more on this in "Pod Lifecycle - Kubernetes".

With that said, anytime a significant change has been made in the lifecycle of a service, in our case the NGINX app, we will have a different IP address which will in turn cause significant downtime in our app which defeats a main purpose of Kubernetes - to help establish a "highly available" application.

Okay, don't panic - we'll get through this ?

Step 3: Create an External DNS Service to Dynamically Point NGINX

In the previous step, with our LoadBalancer spec coupled with EKS we actually created an Elastic Load Balancer (for better or worse).

In this section we'll create a DNS service that points our load balancer via "ALIAS record". This ALIAS record is essentially dynamic in that a new one is created whenever our service changes. The stability is established in the name server records.

The tl;dr for the remaining portion is simply follow the documentation for using ExternalDNS with Route 53. Route 53 is "cloud Domain Name System (DNS) web service".

Below were things I had to do that weren't obvious from the documentation. Hold on to your horses, this gets a little scrappy.

• eksctl utils associate-iam-oidc-provider --cluster=your-cluster-name per eksctl service accounts documentation.
• When creating the IAM policy document per the ExternalDNS documentation, I actually had to do it via CLI vs online in my account. I kept getting this error: WebIdentityErr: failed to retrieve credentials\ncaused by: AccessDenied: Not authorized to perform sts:AssumeRoleWithWebIdentity\n\tstatus code: 403. When I created the policy via CLI the issue went away. Below is the full command you should be able to literally copy and execute if you have the AWS CLI installed.

aws iam create-policy \
  --policy-name AllowExternalDNSUpdates \
  --policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Action":["route53:ChangeResourceRecordSets"],"Resource":["arn:aws:route53:::hostedzone/*"]},{"Effect":"Allow","Action":["route53:ListHostedZones","route53:ListResourceRecordSets"],"Resource":["*"]}]}'

• Use the policy ARN output above to create an IAM role bound to the ExternalDNS service account with a command that will look something like eksctl create iamserviceaccount --cluster=your-cluster-name --name=external-dns --namespace=default --attach-policy-arn=arn:aws:iam::123456789:policy/AllowExternalDNSUpdates.
• We should now have a new role from the above that we can see in the IAM console which will have a name of something like eksctl-foo-addon-iamserviceaccount-Role1-abcdefg. Click on the role from the list and at the top of the next screen make note of the "Role ARN" as something like arn:aws:iam::123456789:role/eksctl-foo-addon-iamserviceaccount-Role1-abcdefg.
• Follow these steps to create a "hosted zone" in Route 53.
• You can confirm things in the Route 53 console.
• If your domain provider allows you to manage DNS settings, add the 4 name server records from the output of the command you ran to create a "hosted zone".
• Deploy ExternalDNS by following the instructions. Afterwards, you can tail the logs with kubectl logs -f name-of-external-dns-pod. You should see a line like this at the end: time="2020-05-05T02:57:31Z" level=info msg="All records are already up to date"

Easy, right?! Okay, maybe not... but at least you didn't have to figure all of that out alone ? There could be some gaps above, but hopefully it helps guide you through your process.

Conclusion

Although this post may have some grey areas, if it helps you establish dynamic DNS resolution as part of a highly available application, you've got something really special ?

Please add comments if I can help clear up anything or correct my terminology!

This post is originally from www.jaredwolff.com

Privacy.

Performance.

Brilliant looks.

Can you have all three?

(Of course!)

Having a statically generated blog is great. Many folks use services like Disqus and Google Analytics to make them even better. Not surprising if you were one of them! Privacy concerns are are the forefront of everyone’s attention. So, rather than keeping the status quo, it’s time to do something about it!

If you've been looking to protect your site visitor's privacy and improve performance this blog post is for you.

In this article we'll be using DigitalOcean’s Docker droplet. It allows you to host several different applications/services on one (virtual) machine. By the end of it you'll know how to run your own comments server using Commento. Plus i’ll share a few tricks i’ve learned along the way to make it much easier for you.

Leeeets go!

Reverse Proxy

One of the most important aspects of this setup is the reverse proxy. A reverse proxy acts like a router. Requests come in for a certain domain. That request is then routed to the service associated with that domain.

Here’s a diagram from the Nginx Reverse Proxy + Let’s Encrypt Helper documentation. It'll help illustrate the idea.

Another benefit is that there’s an extra layer of protection to the outside world. Your websites run in a private network and the only access is through the Nginx reverse proxy. Point your DNS to the server and Nginx handles all the magic.

Here's how to get it setup:

1. Go ahead and set up your Digital Ocean Droplet. All the info you need is right here. The $5 version is more than sufficient.

2. Go here to clone the repository. You can also run this in your terminal. Make sure you SSH into your Digital Ocean droplet first!

   git clone git@github.com:evertramos/docker-compose-letsencrypt-nginx-proxy-companion.git

3. Change directories to the cloned repository.

4. Copy .env.sample to .env and update the values inside. I had to change the IP value to the IP of my Digital Ocean Droplet. I left all the other ones alone.
5. Run docker-compose up -d to start everything. (you can run without the -d option to make sure everything starts ok. Or you can attach the log output using docker container logs -f <container name

When pointing your sub-domains to this server, make sure you use an A record. Here's an example of mine:

Depending on your DNS provider, you'll have to figure out how to set an A record. That is beyond the purpose of this article though!

Setting Up Commento with Docker Compose

Here is the current docker compose file i'm using for Commento. It includes a few more environment variables for configuring Github, Gitlab and Google. It also includes the environment variables for setting the SMTP settings. These parameters are important. Otherwise you can't receive password reset or moderation emails!

version: '3'

services: commento: image: registry.gitlab.com/commento/commento container_name: commento restart: always environment: COMMENTO_ORIGIN: https://${COMMENTS_URL} COMMENTO_PORT: 8080 COMMENTO_POSTGRES: postgres://postgres:postgres@postgres:5432/commento?sslmode=disable COMMENTO_SMTP_HOST: ${SMTP_HOST} COMMENTO_SMTP_PORT: ${SMTP_PORT} COMMENTO_SMTP_USERNAME: ${SMTP_USERNAME} COMMENTO_SMTP_PASSWORD: ${SMTP_PASSWORD} COMMENTO_SMTP_FROM_ADDRESS: ${SMTP_FROM_ADDRESS} COMMENTO_GITHUB_KEY: ${COMMENTO_GITHUB_KEY} COMMENTO_GITHUB_SECRET: ${COMMENTO_GITHUB_SECRET} COMMENTO_GITLAB_KEY: ${COMMENTO_GITLAB_KEY} COMMENTO_GITLAB_SECRET: ${COMMENTO_GITLAB_SECRET} COMMENTO_GOOGLE_KEY: ${COMMENTO_GOOGLE_KEY} COMMENTO_GOOGLE_SECRET: ${COMMENTO_GOOGLE_SECRET} COMMENTO_TWITTER_KEY: ${COMMENTO_TWITTER_KEY} COMMENTO_TWITTER_SECRET: ${COMMENTO_TWITTER_SECRET} VIRTUAL_HOST: ${COMMENTS_URL} VIRTUAL_PORT: 8080 LETSENCRYPT_HOST: ${COMMENTS_URL} LETSENCRYPT_EMAIL: ${EMAIL} depends_on:

• postgres networks:
• db_network

• webproxy

  postgres: image: postgres container_name: postgres environment: POSTGRES_DB: commento POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres networks:

• db_network volumes:

• postgres_data_volume:/var/lib/postgresql/data

  networks: db_network: webproxy: external: true

  volumes: postgres_data_volume:

To set the environment variables, put them inside an .env file. Make sure the .env file is in the same directory as docker-compose.yml. When you run docker-compose up it will apply the variables set in the .env file. Nothing gets set if they're left blank.

Set the required COMMENTS_URL and EMAIL or you may run into problems. The best way to set these is by pacing them in the .env file. Here is an example:

COMMENTS_URL=comments.your.url EMAIL=you@your.url

Getting OAuth Key & Secret

Commento works with most popular OAuth providers. Thus visitors can leave comments without making an account.

The instructions are similar for each. I've outlined the steps for all of them below.

Twitter

1. Login to Twitter.com and apply for a developer account: https://developer.twitter.com/en/application/use-case

   

2. Describe how you'll use the API. You can use what I wrote.

   

3. Double check your entry and click Looks Good!

   

4. Agree to the terms of service.

   

   

5. They'll tell you to check your email for a confirmation. Confirm your email and you should be able to create your first app!

6. Once approved to to Get started click Create an app.

   

7. Next screen, again click Create an app

   

8. Enter all the appropriate details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

9. Finally, once you're done filling out the information to go the Keys and Tokens area. Save both the key and token. Enter them into the .env file. You can use COMMENTO_TWITTER_KEY and COMMENTO_TWITTER_SECRET

   

Gitlab

1. Login to Gitlab.com and go to to top right and click Settings

2. Then click on Applications

   

3. Enter a name for your app. I put Commento.

4. Set the Redirect URI to https://<your URL>/api/oauth/gitlab/callback

5. Select the read_user scope.

   

6. Click the green Save Application button

7. Copy the Application ID and Secret and place them in your .env file using COMMENTO_GITLAB_KEY and COMMENTO_GITLAB_SECRET

   

Github

1. To get your OAuth key and secret, you'll need to go to this URL: https://github.com/settings/developers

2. Once there, click on New OAuth App

   

3. Enter your details. For the callback URL, use https://<your URL>/api/oauth/github/callback where <your URL> is your Commento subdomain.

   

   Note: Make sure you include https in your URLs.

4. Grab the Client ID and Client secret and put that into your .env file using COMMENTO_GITHUB_KEY and COMMENTO_GITHUB_SECRET

   

Google

Setting up Google is just about as tedious to set up as Twitter. Despite how scary I just made it out to be, it's completely doable. Here are the steps.

1. Go to this URL: Google Developer Console

2. Create a new project

   

3. Click the GoogleAPIs logo in the top left corner to go back once you have a project. (Make sure the dropdown next to the GoogleAPIs logo is the same as your new project!)

4. Then, click Credentials on the left side.

5. Update the Application Name and Authorized Domains in the OAuth consent screen

   

6. Click Create credentials then OAuth client ID

   

7. On the Create OAuth client ID enter the subdomain associated with Commento to Authorized Javascript origins. Then, enter the full callback URL. For example https://comments.jaredwolff.com/api/oauth/google/callback. Make it yours by replacing comments.jaredwolff.com with your URL.

   

   Once entered, click the create button.

8. Grab the client ID and client secret

   

9. Update your .env file using COMMENTO_GOOGLE_KEY and COMMENTO_GOOGLE_SECRET

Install your application

You've entered your OAuth Credentials email, domain and SMTP credentials. It's time to wrap this show up!

1. Once you're done editing your .env file. Run docker-compose up (For files not named docker-compose.yml, use the -f flag. Example: docker-compose -f commento.yml up
2. Watch the output for errors. If it looks good you may want to kill it (CTRL+C) and run with the -d flag

3. On first start, Commento will prompt you with a login screen.

   

4. Create a new account by clicking Don't have an account yet? Sign up.

5. Enter your information and click Sign Up

6. Check your email and click the included link:

   

7. Log in with your freshly made account.

8. Then, click Add a New Domain.

   

9. Once created go to Installation Guide. Copy the snippet and place it where ever you want your comments to live. In my case, I put the snippet in an area just after my <article> tag.

   

10. Re-compile your site and check for success!

    

    Checkmark! Finally, I recommend you try logging in with each individual OAuth configuration. That way you know it working for your website visitors. ?

Alternatives

I spent a good chunk playing around with some of the alternatives. This is by no means a definitive guide on what will work best for your site. Here are some of the top ones as of this writing:

https://utteranc.es/#configuration

https://github.com/netlify/gotell

https://github.com/eduardoboucas/staticman

https://posativ.org/isso/

https://www.remarkbox.com

https://www.vis4.net/blog/2017/10/hello-schnack/

https://github.com/gka/schnack

There's also a huge thread over at the Hugo blog which has a ton more links and resources as well:

https://discourse.gohugo.io/t/alternative-to-disqus-needed-more-than-ever/5516

Conclusion

Congrats! You are now hosting your own comments server! ?

In this article you've learned how to harness the power of Docker and a Nginx Reverse Proxy. As an added bonus, you know how to set up OAuth credentials! That way future setup will be easy peasy.

By the way, this is only the tip of the iceberg. You can set up the same server for analytics, data collection and more. All the example code including code for other applications can be found here.

Finally, if you're looking pay for Commento head to www.commento.io and sign up for the service. You'll be supporting awesome open source software!

If you have comments and questions let's hear em'. Start the conversation down below. ???

If you're tired of hearing your coworkers praise Docker and its benefits at every chance they get, or you're tired of nodding your head and walking away every time you find yourself in one of these conversations, you've come to the right place.

Also, if you are looking for a new excuse to wander off without getting fired, keep reading and you'll thank me later.

_Source: [developermemes](http://www.developermemes.com" rel="noopener" target="blank" title=")

Docker

Here's Docker's definition, according to Wikipedia:

Docker is a computer program that performs operating-system-level virtualization.

Pretty simple, right? Well, not exactly. Alright, here's my definition of what docker is:

Docker is a platform for creating and running containers from images.

Still lost? No worries, that's because you probably don't know what containers or images are.

Images are single files containing all the dependencies and configurations required to run a program, while containers are the instances of those images. Let's go ahead and see an example of that in practice to make things clearer.

Important note: Before you continue, make sure you install docker using the recommended steps for your operating system.

Part 1. "Hello, World!" from a Python image

Let's say you don't have Python installed in your machine — or at least not the latest version - and you need python to print "Hello, World!" in your terminal. What do you do? You use docker!

Go ahead and run the following command:

docker run --rm -it python:3 python

Don't worry, I'll explain that command in a second, but right now you are probably seeing something like this:

It might take a few moments for this command to run for the first time

That means we are currently inside a docker container created from a python 3 docker image, running the python command. To finish off the example, type print("Hello, World!") and watch as the magic happens.

A "Hello, World!". Much wow!

Alright, you did it, but before you start patting yourself on the back, let's take a step back and understand how that worked.

Breaking it down

Let's start from the beginning. The docker run command is docker's standard tool to help you start and run your containers.

The --rm flag is there to tell the Docker Daemon to clean up the container and remove the file system after the container exits. This helps you save disk space after running short-lived containers like this one, that we only started to print "Hello, World!".

The -t (or --tty) flag tells Docker to allocate a virtual terminal session within the container. This is commonly used with the -i (or --interactive) option, which keeps STDIN open even if running in detached mode (more about that later).

Note: Don't worry too much about these definitions right now. Just know that you will use the-it flag anytime you want to type some commands on your container.

Lastly, python:3 is the base image we used for this container. Right now, this image comes with python version 3.7.3 installed, among other things. Now, you might be wondering where did this image came from, and what's inside of it. You can find the answers to both of these questions right here, along with all the other python images we could have used for this example.

Last but not least, python was the command we told Docker to execute inside our python:3 image, which started a python shell and allowed our print("Hello, World!") call to work.

One more thing

To exit python and terminate our container, you can use CTRL/CMD + D or exit(). Go ahead and do that right now. After that, try to execute our docker run command again and you'll see something a little bit different, and a lot faster.

Much faster. Wow!

That's because we already downloaded the python:3 image, so our container starts a lot faster now.

Part 2. Automated "Hello World!" from a Python image

What's better than writing "Hello, World!" in your terminal once? You got it, writing it twice!

Since we cannot wait to see "Hello, World!" printed in our terminal again, and we don't want to go through the hustle of opening up python and typing print again, let's go ahead and automate that process a little bit. Start by creating a hello.py file anywhere you'd like.

# hello.py

print("Hello, World!")

Next, go ahead and run the following command from that same folder.

docker run --rm -it -v $(pwd):/src python:3 python /src/hello.py

This is the result we are looking for:

Great! YAHW (Yet Another "Hello World!")

Note: I used ls before the command to show you that I was in the same folder that I created the hello.py file in.

As we did earlier, let's take a step back and understand how that worked.

Breaking it down

We are pretty much running the same command we ran in the last section, apart from two things.

The -v $(pwd):/src option tells the Docker Daemon to start up a volume in our container. Volumes are the best way to persist data in Docker. In this example, we are telling Docker that we want the current directory - retrieved from $(pwd) - to be added to our container in the folder /src.

Note: You can use any other name or folder that you want, not only /src

If you want to check that /src/hello.py actually exists inside our container, you can change the end of our command from python hello.py to bash. This will open an interactive shell inside our container, and you can use it just like you would expect.

Isn't that crazy?

Note: We can only use bash here because it comes pre-installed in the python:3 image. Some images are so simple that they don't even have bash. That doesn't mean you can't use it, but you'll have to install it yourself if you want it.

The last bit of our command is the python /src/hello.py instruction. By running it, we are telling our container to look inside its /src folder and execute the hello.py file using python.

Maybe you can already see the wonders you can do with this power, but I'll highlight it for you anyway. Using what we just learned, we can pretty much run any code from any language inside any computer without having to install any dependencies at the host machine - except for Docker, of course. That's a lot of bold text for one sentence, so make sure you read that twice!

Part 3. Easiest "Hello, World!" possible from a Python image using Dockerfile

Are you tired of saying hello to our beautiful planet, yet? That's a shame, cause we are gonna do it again!

The last command we learned was a little bit verbose, and I can already see myself getting tired of typing all of that code every time I wanna say "Hello, World!" Let's automate things a little bit further now. Create a file named Dockerfile and add the following content to it:

# Dockerfile

FROM python:3

WORKDIR /src/app

COPY . .

CMD [ "python", "./hello.py" ]

Now run this command in the same folder you created the Dockerfile:

docker build -t hello .

All that's left to do now is to go crazy using this code:

docker run hello

Note that you don’t even need to be in the same folder anymore

You already know how it is. Let's take a moment to understand how a Dockerfile works now.

Breaking it down

Starting with our Dockerfile, the first line FROM python:3 is telling Docker to start everything with the base image we are already familiar with, python:3.

The second line, WORKDIR /src/app, sets the working directory inside our container. This is for some instructions that we'll execute later, like CMD or COPY. You can see the rest of the supported instructions for WORKDIR right here.

The third line, COPY . . is basically telling Docker to copy everything from our current folder (first .), and paste it on /src/app (second .). The paste location was set with the WORKDIR command right above it.

Note: We could achieve the same results by removing the WORKDIR instruction and replacing the COPY . . instruction with COPY . /src/app. In that case, we would also need to change the last instruction, CMD ["python", "./hello.py"] to CMD ["python", "/src/app/hello.py"].

Finally, the last line CMD ["python", "./hello.py"] is providing the default command for our container. It's essentially saying that every time we run a container from this configuration, it should run python ./hello.py. Keep in mind that we are implicitly running /src/app/hello.py instead of only hello.py, since that's what where we pointed our WORKDIR to.

Note: The CMD command can be overwritten at runtime. For instance, if you want to run bash instead, you would do docker run hello bash after building the container.

With our Dockerfile finished, we go ahead and start our build process. The docker build -t hello . command reads all the configuration we added to our Dockerfile and creates a docker image from it. That's right, just like the python:3 image we've been using for this entire article. The . at the end tells Docker that we want to run a Dockerfile at our current location, and the -t hello option gives this image the name hello, so we can easily reference it at runtime.

After all of that, all we need to do is run the usual docker run instruction, but this time with the hello image name at the end of the line. That will start a container from the image we recently built and finally print the good ol' "Hello, World!" in our terminal.

Extending our base image

What do we do if we need some dependency to run our code that does not come pre-installed with our base image? To solve that problem, docker has the RUN instruction.

Following our python example, if we needed the numpy library to run our code, we could add the RUN instruction right after our FROM command.

# Dockerfile

FROM python:3

# NEW LINERUN pip3 install numpy

WORKDIR /src/app

COPY . .

CMD [ "python", "./hello.py" ]

The RUN instruction basically gives a command to be executed by the container's terminal. That way, since our base image already comes with pip3 installed, we can use pip3 install numpy.

Note: For a real python app, you would probably add all the dependencies you need to a requirements.txt file, copy it over to the container, and then update the RUN instruction to RUN pip3 install -r requirements.txt.

Part 4. "Hello, World!" from a Nginx image using a long-lived detached container

I know you are probably tired of hearing me say it, but I have one more "Hello" to say before I go. Let's go ahead and use our newly acquired docker power to create a simple long-lived container, instead of these short-lived ones we've been using so far.

Create an index.html file in a new folder with the following content.

# index.html

<h1>Hello, World!</h1>

Now, let's create a new Dockerfile in the same folder.

# Dockerfile

FROM nginx:alpine

WORKDIR /usr/share/nginx/html

COPY . .

Build the image and give it the name simple_nginx, like we previously did.

docker build -t simple_nginx .

Lastly, let's run our newly created image with the following command:

docker run --rm -d -p 8080:80 simple_nginx

You might be thinking that nothing happened because you are back to your terminal, but let's take a closer look with the docker ps command.

I had to crop the output, but you’ll see a few other columns there

The docker ps command shows all the running containers in your machine. As you can see in the image above, I have a container named simple_nginx running in my machine right now. Let's open up a web browser and see if nginx is doing its job by accessing localhost:8080.

Hurray! (this is the last time, I promise)

Everything seems to be working as expected, and we are serving a static page through the nginx running inside our container. Let's take a moment to understand how we accomplished that.

Breaking it down

I'm going to skip the Dockerfile explanation because we already learned those commands in the last section. The only "new" thing in that configuration is the nginx:alpine image, which you can read more about it here.

Apart from what is new, this configuration works because nginx uses the usr/share/nginx/html folder to search for an index.html file and start serving it, so since we named our file index.html and configured the WORKDIR to be usr/share/nginx/html, this setup will work right out of the box.

The build command is exactly like the one we used in the last section as well, we are only using the Dockerfile configuration to build an image with a certain name.

Now for the fun part, the docker run --rm -d -p 8080:80 simple_nginx instruction. Here we have two new flags. The first one is the detached (-d) flag, which means that we want to run this container in the background, and that's why we are back at our terminal right after using the docker run command, even though our container is still running.

The second new flag is the -p 8080:80 option. As you might have guessed, this is the port flag, and it's basically mapping the port 8080 from our local machine to the port 80 inside our container. You could have used any other port instead of 8080, but you cannot change the port 80 without adding an additional setting to the nginx image, since 80 is the standard port the nginx image exposes.

Note: If you want to stop a detached container like this one, you can use the docker ps command to get the container's name (not image), and then use the docker stop instruction with the desired container's name at the end of the line.

Part 5. The end

That's it! If you are still reading this, you have all the basics to start using Docker today on your personal projects or daily work.

Let me know what you thought about this article in the comments, and I'll make sure to write a follow-up article covering more advanced topics like docker-compose somewhere in the near future.

If you have any questions, please let me know.

Cheers!

Introduction

Ever tried setting up some sort of server at home? Where you have to open a new port for every service? And have to remember what port goes to which service, and what your home ip is? This is definitely something that works, and people have been doing it for the longest time.

However, wouldn’t it be nice to type plex.example.com, and have instant access to your media server? This is exactly what a reverse proxy will do for you, and combining it with Docker, it’s easier than ever.

Prerequisites

Docker & Docker-Compose

You should have Docker version 17.12.0+, and Compose version 1.21.0+.

Domain

You should have a domain set up, and have an SSL Certificate associated with it. If you don’t have one, then follow my guide here on how to get a free one with LetsEncrypt.

What This Article Will Cover

I’m a firm believer in understanding what you are doing. There was a time where I would follow guides, and have no clue on how to troubleshoot failures. If that’s how you want to do it, here’s a great tutorial, which covers how to set it up. While my articles are lengthy, you should end up with an understanding of how it all works.

What you will learn here, is what a reverse proxy is, how to set it up, and how you can secure it. I do my best to divide the subject into sections, divided by headers, so feel free to jump over a section, if you feel like it. I recommend reading the entire article one time first, before starting to set it up.

What is a Reverse Proxy?

Regular Proxy

Let’s start with the concept of a regular proxy. While this is a term that’s very prevalent in the tech community, it is not the only place it’s used. A proxy means that information is going through a third party, before getting to the location.

Say that you don’t want a service to know your IP, you can use a proxy. A proxy is a server that has been set up specifically for this purpose. If the proxy server you are using is located in, for example, Amsterdam, the IP that will be shown to the outside world is the IP from the server in Amsterdam. The only ones who will know your IP are the ones in control of the proxy server.

Reverse Proxy

To break it into simple terms, a proxy will add a layer of masking. It’s the same concept in a reverse proxy, except instead of masking outgoing connections (you accessing a webserver), it’s the incoming connections (people accessing your webserver) that will be masked. You simply provide a URL like example.com, and whenever people access that URL, your reverse proxy will take care of where that request goes.

Let’s say you have two servers set up on your internal network. Server1 is on 192.168.1.10, and Server2 is on 192.168.1.20. Right now your reverse proxy is sending requests coming from example.com to Server1. One day you have some updates to the webpage. Instead of taking the website down for maintenance, you just make the new setup on Server2. One you’re done, you simply change a single line in your reverse proxy, and now requests are sent to Server2. Assuming the reverse proxy is setup correctly, you should have absolutely no downtime.

But perhaps the biggest advantage of having a reverse proxy, is that you can have services running on a multitude of ports, but you only have to open ports 80 and 443, HTTP and HTTPS respectively. All requests will be coming into your network on those two ports, and the reverse proxy will take care of the rest. All of this will make sense once we start setting the proxy up.

Setting Up the Container

What to Do

docker-compose.yaml:

version: '3'

services:
  reverse:
    container_name: reverse
    hostname: reverse
    image: nginx
    ports:
      - 80:80
      - 443:443
    volumes:
      - <path/to/your/config>:/etc/nginx
      - <path/to/your/certs>:/etc/ssl/private

First of all, you should add a new service to your docker-compose file. You can call it whatever you prefer, in this case I’ve chosen reverse. Here I’ve just chosen nginx as the image, however in a production environment, it’s usually a good idea to specify a version in case there are ever any breaking changes in future updates.

Then you should volume bind two folders. /etc/nginx is where all your configuration files are stored, and /etc/ssl/private is where your SSL certificates are stored. It is VERY important that your config folder does NOT exist on your host first time you’re starting the container. When you start your container through docker-compose, it will automatically create the folder and populate it with the contents of the container. If you have created an empty config folder on your host, it will mount that, and the folder inside the container will be empty.

Why it Works

There isn’t much to this part. Mostly it’s like starting any other container with docker-compose. What you should notice here is that you are binding port 80 and 443. This is where all requests will come in, and they will be forwarded to whatever service you will specify.

Configuring Nginx

What to Do

Now you should have a config folder on your host. Changing to that directory, you should see a bunch of different files and a folder called conf.d. It’s inside conf.d that all your configuration files will be placed. Right now there’s a single default.conf file, you can go ahead and delete that.

Still inside conf.d, create two folders: sites-available and sites-enabled. Navigate into sites-available and create your first configuration file. Here we’re going to setup an entry for Plex, but feel free to use another service that you have set up if you like. It doesn’t really matter what the file is called, however I prefer to name it like plex.conf.

Now open the file, and enter the following:

upstream plex {
  server        plex:32400;
}

server {
  listen        80;
  server_name   plex.example.com;

  location / {
    proxy_pass  http://plex;
  }
}

Go into the sites-enabled directory, and enter the following command:

ln -s ../sites-available/plex.conf .

This will create a symbolic link to the file in the other folder. Now there’s only one thing left, and that is to change the nginx.conf file in the config folder. If you open the file, you should see the following as the last line:

include /etc/nginx/conf.d/*.conf;

Change that to:

include /etc/nginx/conf.d/sites-enabled/*.conf;

In order to get the reverse proxy to actually work, we need to reload the nginx service inside the container. From the host, run docker exec <container-name> nginx -t. This will run a syntax checker against your configuration files. This should output that the syntax is ok. Now run docker exec <container-name> nginx -s reload. This will send a signal to the nginx process that it should reload, and congratulations! You now have a running reverse proxy, and should be able to access your server at plex.example.com (assuming that you have forwarded port 80 to your host in your router).

Even though your reverse proxy is working, you are running on HTTP, which provides no encryption whatsoever. The next part will be how to secure your proxy, and get a perfect score on SSL Labs.

Why it Works

The Configuration File

As you can see, the plex.conf file consists of two parts. An upstream part and a server part. Let’s start with the server part. This is where you are defining the port receiving the incoming requests, what domain this configuration should match, and where it should be sent to.

The way this server is being set up, you should make a file for each service that you want to proxy requests to, so obviously you need some way to distinguish which file to receive each request. This is what the server-name directive does. Below that we have the location directive.

In our case we only need one location, however you can have as many location directives as you want. Imagine you have a website with a frontend and a backend. Depending on the infrastructure you’re using, you’ll have the frontend as one container and the backend as another container. You could then have location / {} which will send requests to the frontend, and location /api/ {} which will send requests to the backend. Suddenly you have multiple services running on a single memorable domain.

As for the upstream part, that can be used for load-balancing. If you’re interested in learning more about how that works, you can look at the official docs here. For our simple case, you just define the hostname or ip address of the service you want to proxy to, and what port is should be proxied to, and then refer to the upstream name in the location directive.

Hostname Vs. IP Address

To understand what a hostname is, let’s make an example. Say you are on your home network 192.168.1.0. You then set up a server on 192.168.1.10 and run Plex on it. You can now access Plex on 192.168.1.10:32400, as long as you are still on the same network. Another possibility is to give the server a hostname. In this case we’ll give it the hostname plex. Now you can access Plex by entering plex:32400 in your browser!

This same concept was introduced to docker-compose in version 3. If you look at the docker-compose file earlier in this article, you’ll notice that I gave it a hostname: reverse directive. Now all other containers can access my reverse proxy by its hostname. One thing that’s very important to note, is that the service name has to be the same as the hostname. This is something that the creators of docker-compose chose to impose.

Another really important thing to remember, is that by default docker containers are put on their own network. This means that you won’t be able to access your container by it’s hostname, if you’re sitting on your laptop on your host network. It is only the containers that are able to access each other through their hostname.

So to sum it up and make it really clear. In your docker-compose file, add the hostname directive to your services. Most of the time your containers will get a new IP every time you restart the container, so referring to it via hostname, means it doesn’t matter what IP your container is getting.

Sites-available & Sites-enabled

Why are we creating the sites-available and sites-enabled directories? This is not something of my creation. If you install Nginx on a server, you will see that it comes with these folders. However because Docker is built with microservices in mind, where one container should only ever do one thing, these folders are omitted in the container. We’re recreating them again, because of how we’re using the container.

And yes, you could definitely just make a sites-enabled folder, or directly host your configuration files in conf.d. Doing it this way, enables you to have passive configuration laying around. Say that you are doing maintenance, and don’t want to have the service active; you simply remove the symbolic link, and put it back when you want the service active again.

Symbolic Links

Symbolic links are a very powerful feature of the operating system. I had personally never used them before setting up an Nginx server, but since then I’ve been using them everywhere I can. Say you are working on 5 different projects, but all these projects use the same file in some way. You can either copy the file into every project, and refer to it directly, or you can place the file in one place, and in those 5 projects make symlinks to that file.

This gives two advantages: you take up 4 times less space than you otherwise would have, and then the most powerful of them all; change the file in one place, and it changes in all 5 projects at once! This was a bit of a sidestep, but I think it’s worth mentioning.

Securing Nginx Proxy

What to Do

Go to your config folder, and create 3 files and fill them with the following input:

common.conf:

add_header Strict-Transport-Security    "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options              SAMEORIGIN;
add_header X-Content-Type-Options       nosniff;
add_header X-XSS-Protection             "1; mode=block";

common_location.conf:

proxy_set_header    X-Real-IP           $remote_addr;
proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
proxy_set_header    X-Forwarded-Proto   $scheme;
proxy_set_header    Host                $host;
proxy_set_header    X-Forwarded-Host    $host;
proxy_set_header    X-Forwarded-Port    $server_port;

ssl.conf:

ssl_protocols               TLSv1 TLSv1.1 TLSv1.2;
ssl_ecdh_curve              secp384r1;
ssl_ciphers                 "ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384 OLD_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 OLD_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256";
ssl_prefer_server_ciphers   on;
ssl_dhparam                 /etc/nginx/dhparams.pem;
ssl_certificate             /etc/ssl/private/fullchain.pem;
ssl_certificate_key         /etc/ssl/private/privkey.pem;
ssl_session_timeout         10m;
ssl_session_cache           shared:SSL:10m;
ssl_session_tickets         off;
ssl_stapling                on;
ssl_stapling_verify         on;

Now open the plex.conf file, and change it to the following (notice lines 6, 9, 10 & 14):

upstream plex {
  server        plex:32400;
}

server {
  listen        443 ssl;
  server_name   plex.example.com;

  include       common.conf;
  include       /etc/nginx/ssl.conf;

  location / {
    proxy_pass  http://plex;
    include     common_location.conf;
  }
}

Now go back to the root of your config folder, and run the following command:

openssl dhparam -out dhparams.pem 4096

This will take a long time to complete, even up to an hour in some cases.

If you followed my article on getting a LetsEncrypt SSL Certificate, your certificates should be located in </path/to/your/letsencrypt/config>/etc/letsencrypt/live/<domain>/ .

When I helped a friend set this up on his system, we ran into some problems where it couldn’t open the files when they were located in that directory. Most likely the cause of some permissions problems. The easy solution to this is to make an SSL directory, like </path/to/your/nginx/config>/certs, and then mount that to the Nginx container’s /etc/ssl/private folder. In the newly created folder, you should then make symbolic links, to the certs in your LetsEncrypt’s config folder.

When the openssl command is done running, you should run the docker exec <container-name> nginx -t to make sure that all the syntax is correct, and then reload it by running docker exec <container-name> nginx -s reload. At this point everything should be running, and you now have a working and perfectly secure reverse proxy!

Why it Works

Looking in the plex.conf file, there is only one major change, and that is what port the reverse proxy is listening on, and telling it that it’s an ssl connection. Then there are 3 places where we’re including the 3 other files we made. While SSL is kind of secure by itself, these other files make it even more secure. However if for some reason you don’t want to include these files, you need to move the ssl-certificate and ssl-certificate-keyinside the .conf file. These are required to have, in order for an HTTPS connection to work.

Common.conf

Looking in the common.conf file, we add 4 different headers. Headers are something that the server sends to the browser on every response. These headers tell the browser to act a certain way, and it is then up to the browser to enforce these headers.

Strict-Transport-Security (HSTS)

This header tells the browser that connections should be made over HTTPS. When this header has been added, the browser won’t let you make plain HTTP connection to the server, ensuring that all communication is secure.

X-Frame-Options

When specifying this header, you are specifying whether or not other sites can embed your content into their sites. This can help avoid clickjacking attacks.

X-Content-Type-Options

Say you have a site where users can upload files. There’s not enough validation on the files, so a user successfully uploads a php file to the server, where the server is expecting an image to be uploaded. The attacker may then be able to access the uploaded file. Now the server responds with an image, however the file’s MIME-type is text/plain. The browser will ‘sniff’ the file, and then render the php script, allowing the attacker to do RCE (Remote Code Execution).

With this header set to ‘nosniff’, the browser will not look at the file, and simply render it as whatever the server tells the browser that it is.

X-XSS-Protection

While this header was more necessary in older browsers, it’s so easy to add that you might as well. Some XSS (Cross-site Scripting) attacks can be very intelligent, while some are very rudimentary. This header will tell browsers to scan for the simple vulnerabilities and block them.

Common_location.conf

X-Real-IP

Because your servers are behind a reverse proxy, if you try to look at the requesting IP, you will always see the IP of the reverse proxy. This header is added so you can see which IP is actually requesting your service.

X-Forwarded-For

Sometimes a users request will go through multiple clients before it reaches your server. This header includes an array of all those clients.

X-Forwarded-Proto

This header will show what protocol is being used between client and server.

Host

This ensures that it’s possible to do a reverse DNS lookup on the domain name. It’s used when the server_name directive is different than what you are proxying to.

X-Forwarded-Host

Shows what the real host of the request is instead of the reverse proxy.

X-Forwarded-Port

Helps identify what port the client requested the server on.

Ssl.conf

SSL is a huge topic in and of itself, and too big to start explaining in this article. There are many great tutorials out there on how SSL handshakes work, and so on. If you want to look into this specific file, I suggest looking at the protocols and ciphers being used, and what difference they make.

Redirecting HTTP to HTTPS

The observant ones have maybe noticed that we are only ever listening on port 443 in this secure version. This would mean that anyone trying to access the site via https://* would get through, but trying to connect through http://* would just get an error. Luckily there’s a really easy fix to this. Make a redirect.conf file with the following contents:

server {
  listen        80;

  server_name   _;

  return 301 https://$host$request_uri;
}

Now just make sure that it appears in your sites-enabled folder, and when you’ve reloaded the Nginx process in the container, all requests to port 80 will be redirected to port 443 (HTTPS).

Final Thoughts

Now that your site is up and running, you can head over to SSL Labs and run a test to see how secure your site is. At the time of writing this, you should get a perfect score. However there is a big thing to notice about that.

There will always be a balance between security and convenience. In this case the weights are heavily on the side of security. If you run the test on SSL Labs and scroll down, you will see there are multiple devices that won’t be able to connect with your site, because they don’t support new standards.

So have this in mind when you are setting this up. Right now I am just running a server at home, where I don’t have to worry about that many people being able to access it. But if you do a scan on Facebook, you’ll see they won’t have as great a score, however their site can be accessed by more devices.

I’ve used letsencrypt in the past for free certs. I have not successfully utilized it since moving over to docker/kestrel/nginx. That all changed today, and I had a hell of a time figuring out what I was doing to get it working.

This whole Unix, docker, nginx, stuff is pretty new (to me), so maybe it’s just something simple I was missing the whole time. Nonetheless, I’m hoping this will help someone else, or me several months down the road if I decide to do it again.

Original Setup

I have a .net core website, being hosted via kestrel, running on docker, with a reverse proxy via nginx. Up until now, that reverse proxying from nginx was only working over http/port 80. I don’t know a whole lot about reverse proxies. From the sound of it, it can take in requests, and forward them to a specific location on behalf of the requester. In my case, the nginx container receives http requests, and nginx forwards that request onto my kestrel hosted .net core site. Is that right? Hopefully!

As mentioned previously, the nginx was only working with http traffic. I was having a lot of trouble getting it working with https, the original configuration is as follows:

docker-compose:

version: '3.6'services:    kritner-website-web:    image: ${DOCKER_REGISTRY}/kritnerwebsite    expose:      - "5000"    networks:      - frontend    restart: always    container_name: kritnerwebsite_web  kritner-website-nginx:    image: nginx:latest    ports:      - "80:80"    volumes:      - ../src/nginx/nginx.conf:/etc/nginx/nginx.conf    depends_on:      - kritner-website-web    networks:      - frontend    restart: always    container_name: kritnerwebsite_nginx

networks:  frontend:

In the docker-compose file, I’m using two separate containers — the website, which exposes port 5000 (on the docker network, not publicly), and nginx which operates on port 80.

nginx.conf

worker_processes 4; events { worker_connections 1024; } http {    sendfile on;     upstream app_servers {        server kritner-website-web:5000;    }     server {        listen 80;         location / {            proxy_pass         http://app_servers;            proxy_redirect     off;            proxy_set_header   Host $host;            proxy_set_header   X-Real-IP $remote_addr;            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;            proxy_set_header   X-Forwarded-Host $server_name;        }    }}

In the config file, we’re setting up an upstream server with the same name that we’re calling our container service from the docker-compose file kritner-website-web:5000.

Note, all the above can be found at this commit point on my website’s repository.

Enter HTTPS

Letsencrypt is a certificate authority that offers free certs to help secure your website. Why is HTTPS via TLS important? Well, there’s a whole lot to that, and how it works. The basic idea is the user’s traffic is encrypted on either end prior to being sent to the other end. This means if you’re on public wifi, and on https, someone that was “sniffing the wire” so to speak, would see that traffic is occurring, but not the content of said traffic. Since both ends are encrypting/decrypting said traffic with the same encryption key.

If you were on an http site, this traffic would be sent back and forth in plain text. Meaning your data is in danger of being eavesdropped on! Maybe I’ll write a bit more about encryption at some point. (note to self) Especially since it’s something I’m doing as my day job!

letsencrypt is a service I’ve used before. There are various implementations to try to make it as easy as possible to use. Through research for this post, I happened upon this.

Although I hadn’t found this page until now, it would have been useful prior to beginning my adventure. I wanted to use letsencrypt along with my docker container website, and nginx, with as little maintenance as possible. letsencrypt certificates are only good for 90 days.

In my research, I happened upon a docker image linuxserver/letsencrypt that promises to utilize nginx, letsencrypt certificate generation, AND auto renewal. Sounds awesome! While the documentation of the image seems mostly adequate — for someone well versed in all this process. I found it to be lacking. The whole setup process took me some time to figure out. Hence this post, to hopefully help out the next person, or again me in the future!

Linux Server.IO logo

Struggles

The things I most struggled with when getting this linuxserver/letsencrypt image up and working were:

• How docker volumes “work” and their relationship with this container
• How to set volumes up to utilize my configuration (related to the above point) — I was initially having a lot of trouble figuring out why my settings changed on the container were being changed back on reloading of said container (because that’s what they’re supposed to do)
• How to set up the correct nginx configuration — where to put it, and what to put in it.

Docker volumes

Docker volumes (doc):

Volumes are the preferred mechanism for persisting data generated by and used by Docker containers. While bind mounts are dependent on the directory structure of the host machine, volumes are completely managed by Docker. Volumes have several advantages over bind mounts

letsencrypt has a lot of configuration to go along with it. It took a while for me to realize, but I needed a volume that mapped from a directory on the docker host to a specific directory on the letsencrypt image. I eventually accomplished this in the compose file like so:

volumes:      - ${DOCKER_KRITNER_NGINX}:/config       - ./nginx.conf:/config/nginx/site-confs/default

The first item in the array (${DOCKER_KRITNER_NGINX}:/config) takes a new environment variable that maps the host directory (defined in the variable) to the /config within the docker container itself. This means that the docker host (at the env var path) will contain the same config as the docker container at the secondary portion of the volume mapping (/config)

The second item (./nginx.conf:/config/nginx/site-confs/default) maps my local repositories nginx.conf file (the file where I set up the reverse proxy) to override the /config/nginx/site-confs/default file on the docker host and container.

The full list of files that I ended up needing to modify for my particular situation was:

• /config/dns-conf/dnsimple.ini
• /config/nginx/site-confs/default

The dnsimple.ini configuration was add my api key, and the …/default houses the nginx configuration.

The final default configuration I ended up with is:

upstream app_servers {        server kritnerwebsite:5000;}

## Version 2018/09/12 - Changelog: https://github.com/linuxserver/docker-letsencrypt/commits/master/root/defaults/default

# listening on port 80 disabled by default, remove the "#" signs to enable# redirect all traffic to httpsserver { listen 80; server_name kritnerwebsite; return 301 https://$host$request_uri;}

# main server blockserver { listen 443 ssl;

# enable subfolder method reverse proxy confs include /config/nginx/proxy-confs/*.subfolder.conf;

# all ssl related config moved to ssl.conf include /config/nginx/ssl.conf;  # enable for ldap auth #include /config/nginx/ldap.conf;

client_max_body_size 0;

location / {            proxy_pass         http://app_servers;            proxy_redirect     off;            proxy_set_header   Host $host;            proxy_set_header   X-Real-IP $remote_addr;            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;            proxy_set_header   X-Forwarded-Host $server_name;    }

}

# enable subdomain method reverse proxy confsinclude /config/nginx/proxy-confs/*.subdomain.conf;# enable proxy cache for authproxy_cache_path cache/ keys_zone=auth_cache:10m;

There are a few changes from the default that was there, which I’ll try to highlight next.

upstream app_servers {        server kritnerwebsite:5000;}

Above is pretty cool, since docker has its own internal DNS (I guess?). You can set up an upstream server by the containers name, in my case “kritnerwebsite”. (Note: I changed it from earlier in the post, which was “kritner-website-web”.)

# listening on port 80 disabled by default, remove the "#" signs to enable# redirect all traffic to httpsserver { listen 80; server_name kritnerwebsite; return 301 https://$host$request_uri;}

Uncommented out this section from the default, applied my server_name of “kritnerwebsite”

# main server blockserver { listen 443 ssl;

# enable subfolder method reverse proxy confs include /config/nginx/proxy-confs/*.subfolder.conf;

# all ssl related config moved to ssl.conf include /config/nginx/ssl.conf;  # enable for ldap auth #include /config/nginx/ldap.conf;

client_max_body_size 0;

location / {            proxy_pass         http://app_servers;            proxy_redirect     off;            proxy_set_header   Host $host;            proxy_set_header   X-Real-IP $remote_addr;            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;            proxy_set_header   X-Forwarded-Host $server_name;    }

}

In the above, it’s mostly from the “default” save for “location” and everything within that object. Here, we’re setting up the reverse proxy to forward requests to “/” (anything) to our http://app_servers (kritnerwebsite as per our upstream).

docker-compose.yml

Our docker compose file didn’t change a whole lot from the initial. There were a few notable changes, which I’ll also get into describing:

version: '3.6'services:    nginx:    image: linuxserver/letsencrypt    ports:      - "80:80"      - "443:443"    volumes:      - ${DOCKER_KRITNER_NGINX}:/config       - ./nginx.conf:/config/nginx/site-confs/default    depends_on:      - kritnerwebsite    networks:      - frontend    container_name: nginx    environment:      - PUID=1001 # get on dockerhost through command "id <user>""      - PGID=1001      - EMAIL=kritner@gmail.com      - URL=kritner.com      - SUBDOMAINS=www      - TZ=America/NewYork      - VALIDATION=dns # using dns validation      - DNSPLUGIN=dnsimple # via dnsimple, note there is additional configuration require separate from this file      # - STAGING=true # this should be uncommented when testing for initial success, to avoid some rate limiting

kritnerwebsite:    image: ${DOCKER_REGISTRY}/kritnerwebsite    networks:      - frontend    expose:      - "5000"    restart: always    container_name: kritnerwebsite  networks:  frontend:

for the new parts:

nginx:    image: linuxserver/letsencrypt

Using a different image — linuxserver/letsencrypt instead of nginx. This image has nginx included, but also certbot, along with a cronjob to run certbot at application start.

ports:      - "80:80"      - "443:443"

Now we’re using both http and https ports (though note, we’re redirecting http calls to https via the nginx config).

volumes:      - ${DOCKER_KRITNER_NGINX}:/config       - ./nginx.conf:/config/nginx/site-confs/default

Already discussed earlier in the post, we’re using these volumes to properly set up the nginx configuration, with our dnsimple api key, as well as our reverse proxying to the kritnerwebsite.

environment:      - PUID=1001 # get on dockerhost through command "id <user>"      - PGID=1001      - EMAIL=kritner@gmail.com      - URL=kritner.com      - SUBDOMAINS=www      - TZ=America/NewYork      - VALIDATION=dns # using dns validation      - DNSPLUGIN=dnsimple # via dnsimple, note there is additional configuration require separate from this file      # - STAGING=true # this should be uncommented when testing for initial success, to avoid some rate limiting

Environment variables needed as per the letsencrypt documentation can be found here.

• PUID/PGID — get on dockerhost through command “id ”
• Email — well, your email (used for cert expiration emails apparently)
• URL — the main domain URL
• subdomains — any subdomains to the URL to be certified
• TZ — timezone
• Validation — the type of validation to do — I’m using DNSimple, so i needed DNS in this field. Other options are html, tls-sni
• dnsplugin — dnsimple — other options are cloudflare, cloudxns, digitalocean, dnsmadeeasy, google, luadns, nsone, rfc2136 and route53 as per the letsencrypt documentation
• Staging=true — I used this for testing out all my various attempts prior to getting it working. letsencrypt has rate limiting when not running in staging mode (or at least in staging it’s harder to run up against).

All the above changes, experimenting, failing, and then finally succeeding can be found in this pull request.

The final result?

Awww yeah

and from https://www.ssllabs.com/ —

Not an “A+”, but really not bad for using one pre-built docker image for my HTTPs needs!

Related:

• Going from an “A” to an “A+” on ssllabs.com

Getting a server up and running for a new project every time might be time-consuming or difficult for new developers. So I thought I’d write a step-by-step guide that will ease the deployment process.

If you’re in no mood to read, you can copy paste each step as described (replace values) and get your server up and running ?

Prerequisites:

1. Amazon Linux EC2 instance up and running with the associated key pair (ssh access to it).
2. Port 22, 80 must be open for this instance.
3. Django application that you want to deploy.
4. Database settings are configured to use PostgreSQL.
5. requirements.txt is present in your app, having dependencies list to install.
6. Git repository for your Django app.

SSH & update ubuntu instance

You need to ssh into your EC2 instance, so make sure you have port 22 open for your instance and then do a update/upgrade.

ssh -i path-to-your-key.pem ubuntu@your-aws-instance-public-ip

sudo apt-get update && sudo apt-get upgrade -y

Installing Python3.6.x on AWS EC2 (ubuntu 16.04)

We will download the tar.xz file from official site and than manually install it. Before that we need to install some required dependencies.

Building and installing dependencies

sudo apt install build-essential checkinstall

sudo apt install libreadline-gplv2-dev libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev libffi-dev

Downloading & manually installing required Python version

cd /opt && sudo wget https://www.python.org/ftp/python/3.6.6/Python-3.6.6.tar.xz

sudo tar -xvf Python-3.6.6.tar.xz

cd Python-3.6.6/

sudo ./configure

sudo make && sudo make install

Removing downloaded file

sudo rm -rf Python-3.6.6.tar.xz

Check Python version

python3 -V
> Python 3.6.6

Setting up Ubuntu user for our application

Django itself is very secure framework, I agree. But web applications are still vulnerable. It is good practice to run your application as system users with limited privileges which has limited access to resources on your server. So in this section, we will be adding a new user & permission group to our EC2 instance.

Adding ubuntu system group ‘groupname’ [webapps in my case] and assign a user ‘username’ [bunny in my case] to this group

sudo groupadd --system webapps
sudo useradd --system --gid webapps --shell /bin/bash --home /webapps/project_name bunny

Note: I am assuming “project_name” is the name that you might have used during “django-admin startproject <name>”

Create a directory to store your application

Create a directory to store your application in /webapps/project_name/. Change the owner of that directory to your application user bunny:

sudo mkdir -p /webapps/project_name/

sudo chown bunny /webapps/project_name/

Allow limited access to other group users to application directory

sudo chown -R bunny:users /webapps/project_name

sudo chmod -R g+w /webapps/project_name

Now you can switch to your user

sudo su - bunny

// your console will switch to something like this
bunny@ip-172-31-5-231:~$

To switch back to sudo user, just do **ctrl+d** and it’ll kill the user terminal.

Installing and configuring PostgresSQL

Installing PostgreSQL & creating database

sudo apt install postgresql postgresql-contrib

sudo su - postgres

postgres@ip-172-31-5-231:~$ psql

postgres=# CREATE DATABASE database_name;

Changing default password for postgres while in psql terminal

postgres=# \password

Deploy Django app on EC2 instance via Git in virtual environment

Deploying your app using a virtual environment allows your app and its requirements to be handled separately. It is good practice to keep your app isolated.

Using the environment concept is handy when you are deploying more than one Django app on a single instance to keep them and their dependencies isolated from each other.

We will be creating a virtual environment in our system user (bunny) directory. Before that we will be installing git as a sudo user.

Installing Git and pulling your code from git repo

sudo apt-get install git

sudo su - bunny

// change to your repo https or ssh link
bunny@ip-172-31-5-231:~$ git remote add origin 

git@github.com:<user>/<user-repo>.git

bunny@ip-172-31-5-231:~$ git pull origin <branch_name>

Note that we haven’t cloned our complete repo here. Instead we manually set our git link and only pulled the branch that we want to deploy to this instance. You may have a different instance for your development, beta, or production ready web app corresponding to each branch on git.

Creating virtual environment using Python3.6 in current directory

bunny@ip-172-31-5-231:~$ python3.6 -m venv .
bunny@ip-172-31-5-231:~$ source bin/activate
(project_name)bunny@ip-172-31-5-231:~$ pip install -r requirements.txt

At this point, we have successfully set up our project. Now we need to run some manage.py command. This will require that we are in the directory where our manage.py is present, or every time we need to give a path to it:

(project_name)bunny@ip-172-31-5-231:~$ python <path-to->manage.py migrate

(project_name)bunny@ip-172-31-5-231:~$ python <path-to->manage.py createsuperuser

(project_name)bunny@ip-172-31-5-231:~$ python <path-to->manage.py collectstatic

Note: collectstatic command requires that the STATIC configuration is setup properly. We are not discussing that here, though, as it is not in the scope of this tutorial.

(project_name)bunny@ip-172-31-5-231:~$ python <path-to->manage.py runserver 0.0.0.0:8000

This will start up the development server on port 8000. Assuming port 8000 is also open for your instance, you can visit your server's domain name or IP address followed by 8000 in your browser.

http://your_server_domain_or_public_IP:8000

http://your_server_domain_or_public_IP:8000/admin

Note: Don’t forget to add your domain or IP to ALLOWED_HOST in your settings.py

Setting up the uWSGI Application Server

Now that we’ve got our project set up and ready to go, we can configure uWSGI to serve our app to the web instead of the lightweight development server provided by Django.

If you’re thinking of running the runserver command on a screen, drop it. The dev server with Django is terribly lightweight, highly insecure, and not scalable.

You can install uWSGI either in virtualenv or globally and configure it accordingly.

In this tutorial, we’ll be installing uWSGI in virtualenv. Before we can install uWSGI, we need the Python development files that the software relies on.

Installing uWSGI along with its dependencies

sudo apt-get install python3-dev

sudo su - bunny

bunny@ip-172-31-5-231:~$ source bin/activate

(project_name)bunny@ip-172-31-5-231:~$ pip install uwsgi

Let’s run the server using uWSGI. This command does the same thing a manage.py runserver would do. You need to replace values accordingly to successfully test with this command.

(project_name)bunny@ip-172-31-5-231:~$ uwsgi --http :8000 --home <path-to-virtualenv> --chdir <path-to-manage.py-dir> -w <project-name>.wsgi

Creating uWSGI configuration file

Running uWSGI from the command line is only useful for testing. For actual deployment, we will create a _._ini file somewhere in our system user directory. This file will contain all the configuration for handling a heavy request load, and can be tweaked accordingly.

Later in this tutorial, we will run uWSGI behind NGINX. NGINX is highly compatible with uWSGI and has built-in support for interacting with uWSGI.

Create a directory conf in your system user directory where you will store uwsgi.ini

(project_name)bunny@ip-172-31-5-231:~$ mkdir conf

(project_name)bunny@ip-172-31-5-231:~$ cd conf

(project_name)bunny@ip-172-31-5-231:~$ nano uwsgi.ini

Copy the below code from the gist and save it I think the comments are explanatory enough for each option.

NOTE: updateMe is supposed to be you project name. It is the same name you gave above while creating the system user directory, so update accordingly.

[uwsgi]

# telling user to execute file
uid = bunny

# telling group to execute file
gid = webapps

# name of project you during "django-admin startproject <name>"
project_name = updateMe

# building base path to where project directory is present [In my case this dir is also where my virtual env is]
base_dir = /webapps/%(project_name)

# set PYTHONHOME/virtualenv or setting where my virtual enviroment is
virtualenv = %(base_dir)

# changig current directory to project directory where manage.py is present
chdir = %(base_dir)/src/

# loading wsgi module
module =  %(project_name).wsgi:application

# enabling master process with n numer of child process
master = true
processes = 4

# enabling multithreading and assigning threads per process
# enable-threads  = true
# threads = 2

# Enable post buffering past N bytes. save to disk all HTTP bodies larger than the limit $
post-buffering = 204800

# Serialize accept() usage (if possibie).
thunder-lock = True


# Bind to the specified socket using default uwsgi protocol.
uwsgi-socket = %(base_dir)/run/uwsgi.sock

# set the UNIX sockets’ permissions to access
chmod-socket = 666

# Set internal sockets timeout in seconds.
socket-timeout = 300

# Set the maximum time (in seconds) a worker can take to reload/shutdown.
reload-mercy = 8

# Reload a worker if its address space usage is higher than the specified value (in megabytes).
reload-on-as = 512

# respawn processes taking more than 50 seconds
harakiri = 50

# respawn processes after serving 5000 requests
max-requests = 5000

# clear environment on exit
vacuum = true

# When enabled (set to True), only uWSGI internal messages and errors are logged.
disable-logging = True

# path to where uwsgi logs will be saved
logto = %(base_dir)/log/uwsgi.log

# maximum size of log file 20MB
log-maxsize = 20971520

# Set logfile name after rotation.
log-backupname = %(base_dir)/log/old-uwsgi.log

# Reload uWSGI if the specified file or directory is modified/touched.
touch-reload = %(base_dir)/src/

# Set the number of cores (CPUs) to allocate to each worker process.
# cpu-affinity = 1

# Reload workers after this many seconds. Disabled by default.
max-worker-lifetime = 300

I am trying to make everything easy with clear explanations. Cross check paths, directory name, and other inputs that you are required to replace.

We need to create the log file and run directory where our socket file will be created, that we just mentioned in our uwsgi.ini:

(project_name)bunny@ip-172-31-5-231:~$ mkdir log

(project_name)bunny@ip-172-31-5-231:~$ mkdir run

(project_name)bunny@ip-172-31-5-231:~$ touch log/uwsgi.log

Make sure to change permissions for these two so that every group or user can write or execute files in these directories:

$ sudo chmod 777 /webapps/updateMe/run

$ sudo chmod 777 /webapps/updateMe/log

Now let’s try running the server using uwsgi.ini that we just created.

(project_name)bunny@ip-172-31-5-231:~$ uwsgi --ini /webapps/updateMe/conf/uwsgi.ini

If everything up until now is setup correctly, then it should be running. If not, then you need to go back to check for anything you missed (like the path/project name, etc).

To check any uswgi log you can cat or tail uwsgi.log:

(project_name)bunny@ip-172-31-5-231:~$ tail log/uwsgi.log

Create a systemd Unit File for uWSGI

At this point if everything is cool, you can even run this command in screen and detach it — but again, this is not a good practice at all. Instead we will create a system service and let systemd (Ubuntu’s service manager) take care of it.

Switch back to sudo user

$ sudo nano /etc/systemd/system/uwsgi.service

and copy paste code from the below gist. Don’t forget to update and crosscheck names/path that suit your app:

[Unit]
Description=uWSGI instance to serve updateMe project
After=network.target

[Service]
User=bunny
Group=webapps
WorkingDirectory=/webapps/project_name/src
Environment="PATH=/webapps/project_name/bin"
ExecStart=/webapps/project_name/bin/uwsgi --ini /webapps/project_name/conf/uwsgi.ini
Restart=always
KillSignal=SIGQUIT
Type=notify
NotifyAccess=all

[Install]
WantedBy=multi-user.target

After you save the above file and close it, you can run following commands:

Reload systemctl daemon to reload systemd manager configuration and recreate the entire dependency tree

$ sudo systemctl daemon-reload

Enable uwsgi service to start on system reboot

$ sudo systemctl enable uwsgi

Start uwsgi service

$ sudo service uwsgi start

Restart uwsgi service

$ sudo service uwsgi restart

Check uwsgi service status

$ sudo service uwsgi status

Take a deep breath here if everything ran smoothly. We just finished setting up most hectic part of this tutorial, so you should be proud.

Next we will setup NGINX, and then we’ll be done! I know this is taking a bit of time, but believe me — once done, you will be as happy as I will be after publishing this tutorial.

Setting Up NGINX on EC2 for uWSGI

NGINX is a lightweight server, and we’ll use it as a reverse proxy.

We could let uWSGI run directly on port 80, but NGINX has a lot more benefits which makes it desirable. Also NGINX natively includes support for uWSGI.

Enough talk, let’s install NGINX on our instance

$ sudo apt-get install nginx

Now when you go to http://your-public-ip-or-address, you will see a Nginx welcome page. This is because NGINX is listening to port 80 according to its default configuration.

NGINX has two directories, sites-available and sites-enabled, that need our attention. sites-available stores all conf files for all available sites on that particular instance. sites-enabled stores the symbolic link for each enabled site to the sites-available directory.

By default, there is only one conf file named default that has basic setup for NGINX. You can either modify it or create a new one. In our case, I am going to delete it:

$ sudo rm -rf /etc/nginx/sites-available/default

$ sudo rm -rf /etc/nginx/sites-enabled/default

Let’s create our nginx-uwsgi.conf file to connect the browser request to the uwsgi server we are running in site-available:

$ sudo nano /etc/nginx/sites-available/nginx-uwsgi.conf

and copy the following code from the gist below:

upstream updateMe_dev {
    server unix:/webapps/updateMe/run/uwsgi.sock;
}

server {
    listen 80;
    server_name your-IP-or-address-here;
    charset utf-8;

    client_max_body_size 128M;

    location /static {
    # exact path to where your static files are located on server 
    # [mostly you won't need this, as you will be using some storage service for same]
        alias /webapps/updateMe/static_local;
    }

    location /media {
    # exact path to where your media files are located on server 
    # [mostly you won't need this, as you will be using some storage service for same]
        alias /webapps/updateMe/media_local;
    }

    location / {
        include uwsgi_params;
        uwsgi_pass updateMe_dev;
        uwsgi_read_timeout 300s;
        uwsgi_send_timeout 300s;
    }

    access_log /webapps/updateMe/log/dev-nginx-access.log;
    error_log /webapps/updateMe/log/dev-nginx-error.log;
}

Create symbolic link into sites-enabled directory for same

$ sudo ln -s /etc/nginx/sites-available/nginx-uwsgi.conf /etc/nginx/sites-enabled/nginx-uwsgi.conf

That’s all, we’re almost there, about to finish up…

Reload systemctl daemon

$ sudo systemctl daemon-reload

Enable nginx service on system reboot

$ sudo systemctl enable nginx

Start Nginx service

$ sudo service nginx start

Test Nginx. It should return OK, Successful as a part of the result.

$ sudo nginx -t

If NGINX fails, you can check its last error-log or access-log on the path specified by us in its conf.

$ tail -f /webapps/updateMe/log/nginx-error.log

$ tail -f /webapps/updateMe/log/nginx-access.log

Restart Nginx Service

$ sudo service nginx restart

Check Nginx Service status

$ sudo service nginx status

You should now be able to reach your app at http://your-public-ip-or-address

Well this is the end of this lengthy tutorial. I hope you got what you expected from it. Thanks for bearing with me.

PS: uWSGI + NGINX + Django is highly customizable to meet any large scale requirements. That being said, core optimization still lies at application level. How you code and make use of Django ORM or Raw SQL query, etc. will help you further.

I’ve been pretty curious ever since one of my developers presented the concept of Progressive Web Apps (PWAs) sometime a few months back to me. And finally I found the time to get my hands a little dirty on it :-)

This article describes my first steps and a high-level intro to PWAs based on the fancy VueJS framework, and concentrates primarily on its deployment to a well secured nginx server.

Here are some lectures I used to dive into this topic:

Progressive Web Apps | Web | Google Developers
_Lighthouse, an open-source, automated tool for improving the quality of your Progressive Web Apps, eliminates much of…_developers.google.comGetting started with PWA using Vue - Pusher Blog
_In this tutorial, have an introduction on how to build a book listing app with progressive web apps using Vue to build…_blog.pusher.com

Here is a rough architecture of the scenario we’re going to set up. As you see, this is more a traditional on-Premise setup where I assume you own a domain thats configured and pointed to your root-server. In this article I do not cover cloud-based deployments:

base architecture

Warmup & nginx install

Let’s start with some prep-work to setup the infrastructure we will use for deployment later:

• If you don’t have it yet, get yourself a domain and a root-server and configure your domains DNS records (for IPv4 and IPv6) to point to your server. I’ll use my personal website www.thomas-reinecke.de as an example here.
• On your server, and I am assuming you have root/sudo access, install nginx (example for apt-based linux distributions like debian or ubuntu).

sudo apt-get install nginx

• create your server definition on /etc/nginx/sites-available/default which can look pretty basic for now

server {    server_name www.thomas-reinecke.de thomas-reinecke.de;    root /server/thomasreinecke/nginx;}

• test your nginx config to make sure its syntax is ok before we move on

> nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is oknginx: configuration file /etc/nginx/nginx.conf test is successful

Configure and secure nginx

Since our plan is to utilize PWA service workers, your web app has to run on HTTPS (and ideally also on HTTP/2) only. In addition we certainly should support Google’s attempts to enforce a more secure web.

Beginning in July 2018 with the release of Chrome 68, Chrome will mark all HTTP sites as “not secure”.

Fortunately Let’s Encrypt provides free SSL certificates for your web server including auto-renewal, and all you need to do is properly secure it.

• install certbot from Let’s Encrypt

sudo apt-get install certbot python3-certbot python-certbot-nginx python3-certbot-nginx

• Based on the initial config of your nginx server we’ve done earlier, certbot provides a pretty comfortable way to create a certificate for your site including an end-2-end reconfiguration of your nginx service to support SSL and redirect HTTP traffic to HTTPs.

sudo certbot --nginx -d thomas-reinecke.de -d www.thomas-reinecke.de

• It’ll ask you whether you want certbot to reconfigure your nginx instance.

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.--------------------------------------------------------------------1: No redirect - Make no further changes to the webserver configuration.2: Redirect - Make all requests redirect to secure HTTPS access. Choose this fornew sites, or if you're confident your site works on HTTPS. You can undo thischange by editing your web server's configuration.--------------------------------------------------------------------Select the appropriate number [1-2] then [enter] (press 'c' to cancel):

• Pick the 2nd option and let it go. Expect your site config in /etc/nginx/sites-available/default to look like this afterwards:

# HTTPS configuration of my siteserver {  server_name thomas-reinecke.de www.thomas-reinecke.de;  root /server/thomasreinecke/nginx;

  location / {    index index.html index.htm;  }

  listen <your_IP>:443 ssl http2;   ssl_certificate <path_to_fullchain.pem>;   ssl_certificate_key <path_to_privkey.pem>;   include /etc/letsencrypt/options-ssl-nginx.conf;   ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; }

# HTTP configuration of my site, in any case redirecting to HTTPSserver {  if ($host = www.thomas-reinecke.de) {    return 301 https://$host$request_uri;  }

  if ($host = thomas-reinecke.de) {    return 301 https://$host$request_uri;  }

  listen <your_IP>:80 default;  server_name thomas-reinecke.de www.thomas-reinecke.de;  return 404; }

• I added the http2 option on HTTPs configuration area of your site, this won’t come from certbot.

More details about this procedure (including what you’d need to do to renew your certificate) can be found here.

It’s now time to get your nginx server going, so we create a simple index.html and re-bounce nginx to pick it up.

echo "Hello World!" > /server/thomasreinecke/nginx/index.htmlsudo systemctl reload nginx

Congratulations, you should now have your secured webpage online. Any access to HTTP will be auto-redirected to HTTPS. You can now test it on https://www.ssllabs.com/ssltest/ and you’ll get an A grade :) How cool is that?

Create your vuejs PWA and deploy it to nginx

Since we have the target deployment infrastructure ready now, it’s time to create your first PWA based on the vuejs CLI.

# install vue cli, skip if you already have itnpm install -g vue-cli

# create vue app based on pwa templatevue init pwa <your_app_name>

On the few questions this script presents to you, provide your project’s name and for the rest simply take the defaults. I won’t dive into actual changes of the app that was just created based on the template. Instead let’s concentrate on the deployment and operational aspect to run this on your secured nginx infrastructure. As the next steps, build your app and then move its dist folder into your nginx web root:

# build your vuejs pwa appcd <folder of your app>npm run build

# copy your dist folder onto your server running nginxscp -r dist/* <your_server>:/server/thomasreinecke/nginx/

# on your server restart nginx to refreshsudo systemctl reload nginx

You should now have your VueJS PWA running on your nginx server:

When you get to this page with a usual HTTP URL, you’ll notice a redirection to HTTPs, which is perfectly what we wanted. Now it’s time to run Google Lighthouse against our site and see how it goes. For more details :

Lighthouse | Tools for Web Developers | Google Developers
_Learn how to set up Lighthouse to audit your web apps._developers.google.com

Open Chrome > use its Developer Tools > Audits > Run audits. Here is what we get from this setup — isn’t that fantastic !?

Conclusion

In this article I showed how to setup a secured environment to run a VueJS-based Progressive Web App on an nginx server. I have to admit, I thought this would be somewhat harder, but the reality was: it took me no longer than ~3hrs in total to get there from zero which was pretty surprising.

Setting up a secured and high-performance infrastructure is really no big deal and I encourage everybody who’s dealing with on-Premise deployments to dive into this.

NGINX is perhaps the most versatile web server out there, and it can beat other servers when configured correctly. It can also do other important things, such as load balancing, HTTP caching, and can be used as a reverse proxy.

Over the years, we’ve seen so many configurations which improve security and increase the performance of your web application overall — allowing you to keep up with latest trends.

I’m going to share the minimalist NGINX config that I found is most optimised which I have been using for new my new tool VisaList. I had to do a lot of searching and researching for improving the last mile performance of my website, and I thought the process might help at least a few others — so I’m sharing it here.

Why?

With these changes, I was able to get the result below for my new web app:

Page Speed Score: Page Speed Insights

Lighthouse Score: Chrome Dev Tools Lighthouse

Server Score: Qualys SSL Server Test

You too can get these performance benefits easily. You don’t need to be a DevOps expert to make these optimisations. So anyone who is new to web applications and is using NGINX will find this very useful.

If you are an expert, then you could leave your opinions in the comments so the new devs like me can learn and build a strong and positive web community around us. ✨Go Web Developers!✨

This article assumes that you’ve got an Ubuntu 16.04 (Xenial) server and a server rendered WebApp Vue.js (or any other JS framework) application ready to be served through NGINX along with the API server. If you haven't installed NGINX and need help doing that, you can check out this article.

So what are these optimisations that I’m talking about? Let’s see the code!

Optimisations

The good news is that you only have to bother about two files. One is your overall NGINX config, which applies to all the web apps (you can have multiple web apps like a website, API, static server, and so on). The other is specific to your domain, which, let’s say, is example.com. Replace example.com with your own domain. Here I’m only using the naked domain without www. I will cover that soon.

Open your NGINX config or domain specific config files by using these commands:

sudo nano /etc/nginx/nginx.conf

sudo nano /etc/nginx/sites-available/example.com

Content Compression

Is Brotli better than GZip? Yes and No. When the browser requests a web page, the server doesn't send it directly byte by byte. Instead, it sends it in a compressed state based on the accepted encodings of the browser. Mostly everyone today uses Gzip, and you may ask why? Because its been around for more than a decade.

So here comes Brotli, which is the latest encoding algorithm developed by Google. Brotli is ~20% more efficient than Gzip. Just keep in mind you should send content in Gzip where Brotli is not supported. Brotli works best with static files rather than dynamic content.

Also make sure you enable the Brotli type for API JSON data only when your client side HTTP library supports it. For example, the Axios library doesn't support Brotli encoding yet.

http {

... 

    # Gzip Settings
    gzip on;
    gzip_disable "msie6";
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 32 16k;
    gzip_http_version 1.1;
    gzip_min_length 250;
    gzip_types image/jpeg image/bmp image/svg+xml text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript image/x-icon;

    # Brotli Settings
    brotli on;
    brotli_comp_level 4;
    brotli_buffers 32 8k;
    brotli_min_length 100;
    brotli_static on;
    brotli_types image/jpeg image/bmp image/svg+xml text/plain text/css application/json application/javascript application/x-javascript text/xml application/xml application/xml+rss text/javascript image/x-icon;
...

}

Once you add these changes, you can check that the content-encoding is showing br in the response headers in Chrome developer tools:

Improve Security

By default, your NGINX doesn't have all the important security headers required which is pretty straightforward actually. These prevent clickjacking attacks, cross-site scripting attacks, and other code injection attacks.

Strict-Transport-Security header is for HTTP Strict Transport Security (HSTS) which also protects from protocol downgrade attacks.

http {

...
   # security headers
   add_header X-Frame-Options "SAMEORIGIN" always;
   add_header X-XSS-Protection "1; mode=block" always;
   add_header X-Content-Type-Options "nosniff" always;
   add_header Referrer-Policy "no-referrer-when-downgrade" always;
   add_header Content-Security-Policy "default-src * data: 'unsafe-eval' 'unsafe-inline'" always;

   add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
...

}

Optimize SSL and Sessions

SSL: Use on TLS and disable SSL (SSL is pretty old and outdated and has lot of vulnerabilities ). Optimise cipher suites, as they are the core of TLS. This is where encryption happens.

Session Cache: Creating a cache of TLS connection parameters reduces the number of handshakes, and thus can improve the performance of your application. Caching is configured using ssl_session_cache directive.

Session Tickets: Session tickets are an alternative to session cache. In case of session cache, information about the session is stored on the server.

OSCP: To have a secure connection to a server, the client needs to verify the certificate which the server presented. In order to verify that the certificate is not revoked, the client (browser) will contact the issuer of the certificate. This adds a bit more overhead to connection initialisation (and thus our page load time).

Use these directives in your NGINX config and you are all set for SSL optimisation.

http {

...  
   # SSL Settings
   ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
   ssl_prefer_server_ciphers on;
   ssl_ciphers ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GC$

   # Optimize session cache
   ssl_session_cache shared:SSL:50m;
   ssl_session_timeout 1d;

   # Enable session tickets
   ssl_session_tickets on;

   # OCSP Stapling
   ssl_stapling on;
   ssl_stapling_verify on;
   resolver 8.8.8.8 8.8.4.4 208.67.222.222 208.67.220.220 valid=60s;
   resolver_timeout 2s;
...

}

Improve Performance: HTTP/2 Support

HTTP/2 has lot of benefits over HTTP, like allowing the browser to download files in parallel, and allowing the server to push resources, among others. All you have to do is to replace http with http2 in your default server block. That’s it, and you get lots and lots of benefits.

server{

...

listen 443 http2 default_server;
    listen [::]:443 http2 default_server;
    server_name example.com;
...

}

Type this command curl -I -L https://example.com and verify the response.

HTTP/2 200
server: nginx
date: Wed, 18 Jul 2018 02:13:32 GMT
content-type: text/html; charset=utf-8
content-length: 216641
vary: Accept-Encoding
....

Reduce Scrapping / Attacks

Limiting the requests to the server is critical, as this can easily deplete the resources and can result in huge billings. This is also important to fend off those who want to scrape and attack our servers. There are basically three types of directives:

• Request Limiting **limit_req** : Limit the number of requests per IP
• Connections Limiting **limit_conn** : Limit the number of Connections per IP
• Bandwidth/Rate Limiting **limit_rate** : Limit the bandwidth rate of data being sent

With the below directive, you can rest easy:

http {

...
   # Limits
   limit_req_log_level warn;
   limit_req_zone $binary_remote_addr zone=reqlimit:10m rate=10r/m;

   limit_conn_zone $binary_remote_addr zone=connlimit:100m;
   limit_conn servers 1000; # Simultaneous Connections
...

}

...
server {
...
   location /api/ {
      # Rate Limiting
      limit_req zone=reqlimit burst=20; # Max burst of request
      limit_req_status 460; # Status to send

      # Connections Limiting
      limit_conn connlimit 20; # Number of downloads per IP       

      # Bandwidth Limiting
      limit_rate 4096k; # Speed limit (here is on kb/s)
   }
...
}

Client-side Caching

Caching static files on the browser is easy, and it saves lot of requests to the server. All you have to do is add these two code blocks and specify the expiration as you please. You can include any other static file extension you deem worthy of caching.

server {

...
    location / {
       ...
       ...
    }
    ...
    ...
    location ~* \.(jpg|jpeg|png|gif|ico)$ {
       expires 30d;
    }
    location ~* \.(css|js)$ {
       expires 7d;
    }
...

}

Microcaching

If you haven’t heard about this until now, then you are in luck today! Microcaching is a caching technique in which content is cached for a very short period of time, perhaps as little as 1 second. This effectively means that updates to the site are delayed by no more than a second, which in many cases is perfectly acceptable. This is particularly useful for API responses which are the same for all users.

Use these directives to set microcaching with the path at /tmp/cacheapi with 100MB cache with a max size of 1GB of cache folder that updates cache in the background. Learn more about it here and here.

proxy_cache_path /tmp/cacheapi levels=1:2 keys_zone=microcacheapi:100m max_size=1g inactive=1d use_temp_path=off;
...

server {

...
   location /api/ {

      # Micro caching
      proxy_cache microcacheapi;
      proxy_cache_valid 200 1s;
      proxy_cache_use_stale updating;
      proxy_cache_background_update on;
      proxy_cache_lock on;
      ...
      ...

   }
...

}

http {

...
   add_header X-Cache-Status $upstream_cache_status;
...

}

SSL Certificate

Let’s Encrypt is a Certificate Authority (CA) that provides an easy way to obtain and install free TLS/SSL certificates. This enables encrypted HTTPS on web servers. It simplifies the process by providing a software client, Certbot, that attempts to automate most (if not all) of the required steps.

Install LetsEnctypt:

sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-nginx

Create a LetsEncrypt SSL certificate with this command:

sudo certbot --nginx -d example.com -d www.example.com

and then add these certificates to your domain config file like this:

server {

    listen 443 ssl http2 default_server;
    listen [::]:443 ssl http2 default_server;
...
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
...

}

Redirect WWW

Google prefers that you choose a domain with www instead of without. It’s better to choose the naked domain as its smaller and removes the redundant www . You can now redirect all www users to your naked domain by adding these below directives.

server {
...
...
}
server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    return 301 https://$server_name$request_uri;
}
server {
    listen 80;
    listen [::]:80;
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name www.example.com;
    return 301 https://example.com$request_uri;
}

Pagespeed Module

Pagespeed Module is a gem unknown to many. It was originally a Google Project which is now part of Apache Incubator. Pagespeed can automatically take care of almost all the known ways to improve performance on your website.

Install or Upgrade NGINX with Pagespeed. This is not an easy task, and that’s why I have saved it for last. Follow these instructions, and you should be able to do it without any hastle. Once you’re done, all you need to do is enable it and voilà!

server{

...  
    # Pagespeed Module
    pagespeed on;

    pagespeed FileCachePath /var/cache/ngx_pagespeed_cache;
    location ~ "\.pagespeed\.([a-z]\.)?[a-z]{2}\.[^.]{10}\.[^.]+" {
    add_header "" "";
    }
    location ~ "^/pagespeed_static/" { }
    location ~ "^/ngx_pagespeed_beacon$" { }

    pagespeed RewriteLevel PassThrough;
    pagespeed EnableCachePurge on;
    pagespeed PurgeMethod PURGE;

    pagespeed EnableFilters prioritize_critical_css;
...
}

There are so many filters that you can enable, but just keep in mind that most of the modern frameworks like (Nuxt.js, Angular, Next.js and so on) have some of these optimisations as part of their build process, so this can be counterintuitive. Choose filters which you need and enable only them. This is not by any means an exhaustive set of filters, but would definitely take your site to 100/100 on pagespeed.

pagespeed EnableFilters rewrite_css;
pagespeed EnableFilters collapse_whitespace,remove_comments;
pagespeed EnableFilters flatten_css_imports;
pagespeed EnableFilters combine_css;
pagespeed EnableFilters combine_javascript;
pagespeed EnableFilters defer_javascript;
pagespeed EnableFilters extend_cache;
pagespeed EnableFilters pedantic;
pagespeed EnableFilters inline_google_font_css;
pagespeed FetchHttps enable;
pagespeed EnableFilters inline_css,move_css_above_scripts;
pagespeed EnableFilters inline_javascript;
pagespeed EnableFilters inline_import_to_link;
pagespeed EnableFilters lazyload_images;
pagespeed EnableFilters insert_dns_prefetch;
pagespeed EnableFilters inline_preview_images;
pagespeed EnableFilters resize_mobile_images;
pagespeed EnableFilters rewrite_images;
pagespeed EnableFilters responsive_images,resize_images;
pagespeed EnableFilters responsive_images_zoom;
pagespeed EnableFilters rewrite_javascript;
pagespeed EnableFilters rewrite_style_attributes,convert_meta_tags;

You can read more about different types of filters available here.

So the final NGINX config and domain config looks something like this:

https://gist.github.com/1hakr/01cb00dfce8c92a15c0d9faee9052042

Now all you have to do is reload your NGINX config file by typing the below commands and you have supercharged your NGINX server:

sudo nginx -t

sudo systemctl restart nginx

Pro Tip: If you find this article beyond your reach, then there is a simple website which can get the final config file for you: check out NGINX Config.

I hope you like this NGINX config and are able to supercharge your web apps. Do you already use something similar or have a different opinion altogether? Let me know in the comments.

This is my new microstartup, VisaList, where I have applied these optimisations. It can help you find visa requirements for all countries in the world in a simple and useful way.

Find countries to visit across the world
Search from list of countries your can travel with Visa free, Visa on arrival and other requirements from more than…
visalist.io

That all folks! This is HaKr signing off. Thanks for reading, and if you found this useful do click ? to recommend this article to others so they can find it, too.

I build microstartups while travelling when I can. If you find this kind of stuff interesting, you can follow me on Twitter and check out my open-source work on GitHub.