Apply for Free SSL Certificates

1. Introduction

The Docker - NGINX type deployment node is used to automatically deploy SSL certificates applied for in CertOne to nginx containers.

If the official image does not meet your needs, you can refer to the [Docker Custom] documentation, and introduce our official push-node binary package in the Dockerfile for building custom containers to achieve automated certificate deployment.

2. Usage

To use the Docker - NGINX type deployment node, you need to use our official nginx container image certone/certone-nginx.
This image is built based on the nginx official stable image nginx:1.16 with certificate renewal service added. The other content and usage methods in the certone/certone-nginx image are completely consistent with the nginx official image, please use with confidence.

Pull image command:

 # Docker Hub
 docker pull certone/certone-nginx

When using this image, you need to set the following two environment variables:

• PUSH_NODE_ID: The deployment node ID generated by the system after the deployment node is created. Deployment node IDs all start with push, example: push-53ejqm8p60gd7no9
• PUSH_NODE_TOKEN: The 32-bit token generated by clicking the generate button when creating the deployment node, example: 6b2440b1e3f180a3c9453f9d7766a565

When a container using this image starts for the first time, it will pull the latest certificate from the CertOne server based on the configured PUSH_NODE_ID and PUSH_NODE_TOKEN. If the deployment node corresponding to PUSH_NODE_ID is configured as a deployment node for multiple certificates, multiple certificates will be pulled simultaneously. The pulled certificate files are stored in the /etc/nginx/certificates folder in the container, and then stored in subfolders according to certificate ID (certificate ID is the certificate ID generated by the system after certificate creation is complete, certificate IDs all start with cert, example: cert-2enm4pr1q09g3x5z), then the full path of certificate files is:

• Private key file cert.key (PEM format):

`/etc/nginx/certificates/${certificateID}/cert.key`

• Certificate file fullchain.cer (PEM format):

`/etc/nginx/certificates/${certificateID}/fullchain.cer`

Replace the '${certificateID}' part in the above path with your certificate ID to get the storage path of the corresponding file in the container. Note: Before starting the container, please complete the certificate deployment node configuration and associate the certificate with the deployment node, otherwise the container will fail to start successfully.

3. Best Practices

  Here we will give an example to illustrate how to use the Docker - NGINX type deployment node. For example, we created a Docker - NGINX type deployment node with PUSH_NODE_ID and PUSH_NODE_TOKEN values:

• PUSH_NODE_ID: push-53ejqm8p60gd7no9
• PUSH_NODE_TOKEN: 6b2440b1e3f180a3c9453f9d7766a565

We applied for a single domain certificate for the domain www.example.com, and the certificate ID of this certificate is cert-2enm4pr1q09g3x5z. Then we configured the node we just created as one of the deployment nodes for this certificate in the certificate configuration. The certificate file paths in the container are:

• Private key file cert.key (PEM format): /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/cert.key
• Certificate file fullchain.cer (PEM format): /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/fullchain.cer

Our nginx configuration file nginx.conf content is:

user  nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

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

    server {
        listen              443 ssl;
        server_name         www.example.com;
        ssl_certificate     /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/fullchain.cer;
        ssl_certificate_key /etc/nginx/certificates/cert-2enm4pr1q09g3x5z/cert.key;

        include /etc/nginx/default.d/*.conf;

        location / {
            root   /usr/share/nginx/html;
            index  index.html;
        }
    }
}

The corresponding Dockerfile is:

FROM certone/certone-nginx
WORKDIR /etc/nginx
COPY ./nginx.conf /etc/nginx/nginx.conf
ENV PUSH_NODE_ID='push-53ejqm8p60gd7no9'
ENV PUSH_NODE_TOKEN='6b2440b1e3f180a3c9453f9d7766a565'

Generate your own image based on the above Dockerfile.

4. FAQ

1. After container starts, container logs keep showing: "certificates loading ..."

When encountering this situation, check the following two points in order:

• Please check in CertOne whether the deployment node has been bound to the certificate. Deployment nodes can only automatically pull corresponding certificates after being bound to certificates
• Please check whether the environment variables PUSH_NODE_ID and PUSH_NODE_TOKEN in the container are set correctly and effective. You can use the following commands to check:

# nginx in the command below is the container name, replace with your actual container name
# The command below will open the shell execution environment in the container to execute echo command to check environment variables
docker exec -it nginx bash

# Execute the following two commands in the opened container shell execution environment to check whether the environment variables exist in the container and are consistent with those in CertOne
# If the execution results of the following two commands are empty or inconsistent with those in CertOne, the environment variables are not effective or set incorrectly. Please check whether these two environment variables are correctly set in the container startup command or docker-compose.yml file
echo $PUSH_NODE_ID
echo $PUSH_NODE_TOKEN

If both of the above items are correct and the problem still exists, please contact customer service for resolution