1. Introduction
The Docker - Custom type deployment node is used to automatically deploy SSL certificates applied for in CertOne to user-defined containers.
2. Usage
To use the Docker - Custom type deployment node, you need to introduce our official push-node binary package in the Dockerfile for building custom containers to achieve real-time certificate renewal.
The official push-node code has been open-sourced: https://github.com/certone/push-node. Below is the specific introduction and usage instructions.
push-node
push-node is a certificate renewal service developed in CertOne to achieve real-time automated deployment of certificates to custom containers
Its principle is to subscribe to CertOne server-side certificate update events internally through socket.io to achieve real-time automatic certificate renewal in custom containers
Docker containers for services such as nginx, httpd, openresty can be combined with push-node to achieve automated certificate renewal for corresponding services
In addition to being used in combination with containers, it can also be used independently. Users can judge how to use it more conveniently according to their own needs
How to Use
- Create a [Container - Custom] type deployment node in CertOne
- Bind certificates that need to be deployed to this node with this node in CertOne
- Write the container Dockerfile file, you can refer to Usage Example 01 below
- Build container image through Dockerfile file and create container instance
- After the container instance starts, push-node will automatically pull the bound certificate files from the server to the local
- After push-node successfully pulls the certificate for the first time, it will execute service-start-cmd to start the related service using the certificate, such as nginx, etc.
- After push-node successfully renews the certificate each time, it will execute service-reload-cmd to restart the related service using the certificate, such as nginx, etc.
Parameter Description
- node-id:
- Required, [Container - Custom] type deployment node ID applied for in CertOne
- node-token:
- Required, [Container - Custom] type deployment node TOKEN applied for in CertOne
- cert-folder:
- Optional, certificate folder, default is "/etc/certone/certificates/"
- For example, if the deployment node has bound certificate "cert-2enm4pr1q09g3x5z", then the paths of the corresponding certificate files for this certificate are:
- Private key file cert.key (PEM format): /etc/certone/certificates/cert-2enm4pr1q09g3x5z/cert.key
- Certificate file fullchain.cer (PEM format): /etc/certone/certificates/cert-2enm4pr1q09g3x5z/fullchain.cer
- service-start-cmd:
- Optional, startup command executed after certificate file is downloaded for the first time, for example "nginx -c /etc/nginx/nginx.conf", can achieve starting nginx after certificate is downloaded for the first time
- service-reload-cmd:
- Optional, reload command executed after certificate file is renewed each time, for example "nginx -c /etc/nginx/nginx.conf -s reload", achieves restarting nginx after certificate is renewed each time
Binary Packages
- push-node-alpine-arm64:
- push-node-alpine-x64:
- push-node-linux-arm64:
- push-node-linux-x64:
- push-node-macos-arm64:
- push-node-macos-x64:
- Note: Please select the appropriate binary package according to the system architecture when using
- Note: For the latest version, please check the release list
Usage Example 01
Used with container, system is alpine-x64, service is nginx
nginx container combined with push-node to achieve automated certificate renewal in nginx container
You can view the complete example code in this repository: https://github.com/certone/push-node/tree/main/examples/nginx
Note: Need to download push-node-alpine-x64 binary file to local in advance, copy it into container image through COPY command
FROM nginx:stable-alpine
# Delete default logs in official container image
# Otherwise nginx startup command will report log permission exception
RUN unlink /var/log/nginx/access.log
RUN unlink /var/log/nginx/error.log
# Set current working folder
WORKDIR /etc/nginx
# Copy nginx configuration file
COPY ./nginx.conf .
# Copy push-node binary package
COPY ./push-node-alpine-x64 .
# Add executable permission for push-node
RUN chmod a+x ./push-node-alpine-x64
# Set container startup command
ENTRYPOINT ["./push-node-alpine-x64", "--node-id=push-mlyxpro7vo0ez6jw", "--node-token=b4f2f70c85466671bc06d7f1f469395d", "--cert-folder=/etc/nginx/certificates/", "--service-start-cmd='nginx'", "--service-reload-cmd='nginx -s reload'"]
Usage Example 02
Independent use, system is macos-x64, service is nginx
nginx combined with push-node to achieve automated certificate renewal in nginx
// Download push-node binary file corresponding to macos-x64 system
wget https://github.com/certone/push-node/releases/download/1.0.0/push-node-macos-x64
// Add execution permission for push-node
chmod a+x ./push-node-macos-x64
// Start push-node
./push-node-macos-x64 --node-id=push-mlyxpro7vo0ez6jw \
--node-token=b4f2f70c85466671bc06d7f1f469395d \
--cert-folder=./certificates/ \
--service-start-cmd="nginx" \
--service-reload-cmd="nginx -s reload"
Usage Example 03
Run as system service in background, system is ubuntu, service is nginx .
nginx combined with push-node to achieve automated certificate renewal in nginx
- Download and extract certone executable file
// Download push-node binary file corresponding to linux-x64 system
wget https://github.com/certone/push-node/releases/download/1.0.0/push-node-linux-x64
// Add execution permission for push-node
chmod a+x ./push-node-linux-x64
- Create push-node startup file in push-node folder: start.sh
./push-node-linux-x64 --node-id=push-mlyxpro7vo0ez6jw \
--node-token=b4f2f70c85466671bc06d7f1f469395d \
--cert-folder=./certificates/ \
--service-start-cmd="nginx" \
--service-reload-cmd="nginx -s reload"
- Create system service file: /etc/systemd/system/certone.service
Please modify the push-node file path of certone in the configuration to the actual file path
[Unit]
Description=CertOne
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/home/ubuntu/push-node
ExecStart=/bin/bash /home/ubuntu/push-node/start.sh
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
- Restart systemd and start certone service
# Restart systemd
sudo systemctl daemon-reload
# Start certone service
systemctl start certone
# Allow certone service to start automatically on boot
systemctl enable certone
# View certone service status
systemctl status certone