mashmb/nginx-certbot repository overview

⁠nginx-certbot

Official nginx (1.31.3) image with certbot (2.1.0) and crontab installed.

⁠About image

Image was created to automate SSL certificate generation and renewal (enable HTTPS for websites). It depends on official nginx image (tag of this image always indicates to used nginx image). Additionally certbot was installed with version mentioned above and crontab.

⁠How to use image?

First of all, everything in nginx documentation⁠ is up to date and can be used. How SSL certificate generation and renewal is automated? Image has installed crontab with only one job declared - renew SSL certificates for all websites behind nginx every 12 hours. Compose file can look like this:

services:
  nginx-certbot:
    image: mashmb/nginx-certbot:1.31.3
    ports:
      - 80:80
      - 443:443
    volumes:
      - [path]/nginx.conf:/etc/nginx/nginx.conf
      - [path]/conf.d:/etc/nginx/conf.d
      - [path]/letsencrypt:/etc/letsencrypt

As it is shown, nginx.conf file, directories with additional configuration per website and certificates are mounted from host. Website configuration should be prepared in two variants - HTTP and HTTPS:

upstream [name] {
	# proxy to container
	server [service_name]:[service_port];
}

# Without HTTPS
server {
	listen 80;
	server_name [server_name];

	location / {
		proxy_pass http://[upstream];
		proxy_set_header Host $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
	}
}

# With HTTPS
server {
	listen 80;
	server_name [server_name];

	location / {
		return 301 https://$host$request_uri;
	}
}

server {
	listen 443 ssl;
	server_name [server_name];

	ssl_certificate /etc/letsencrypt/live/[server_name]/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/[server_name]/privkey.pem;

	location / {
		proxy_pass http://[upstream];
		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-Proto "https";
	}
}

For first container run, HTTP configuration should be used (comment configuration for HTTPS). This step is needed because without initial certificates nginx image will not start. When container is up, launch bash in it:

docker exec -it [container_id] bash

Now initial certificates can be generated:

certbot --nginx -d [server_name]

Follow the instructions of executed command. Probably do not allow certobt to update nginx configuration (it will disappear after container restart). When initial certificates are generated, stop the container. Change nginx configuration for chosen website to HTTPS (uncomment HTTPS section and comment HTTP section from above example configuration). Now nginx container can be launched and SSL certificates will be renewed every 12 hours. Described steps should be realized for every new website that needs to be accessed over HTTPS, for rest time image automates certificates renewal process.

⁠Limitations

Usage of templates mentioned in nginx docker image documentation⁠ is unavailable but for sure mounting conf.d directory is working as available workaround.