unsopenhub/oci-dns-certbot repository overview

⁠OCI DNS Certbot

Renew Let's Encrypt certificates through Oracle Cloud Infrastructure (OCI) DNS-01 challenges. The image runs as a short-lived Podman or Docker job: it updates the certificate and atomically exports it for dependent services.

⁠Image

docker pull unsopenhub/oci-dns-certbot:1.1.1
# or use the current stable release:
docker pull unsopenhub/oci-dns-certbot:latest

Published for linux/amd64 and linux/arm64.

⁠Quick start

Create /etc/oci-dns-certbot.env:

CERT_DOMAINS=service.example.com,*.service.example.com
[email protected]
CERTBOT_MANUAL_PROPAGATION_SECONDS=90

OCI_AUTH_USER=ocid1.user.oc1..example
OCI_AUTH_TENANCY=ocid1.tenancy.oc1..example
OCI_AUTH_FINGERPRINT=aa:bb:cc:dd:...
OCI_AUTH_REGION=eu-frankfurt-1
OCI_AUTH_COMPARTMENT=ocid1.compartment.oc1..example
OCI_AUTH_KEY_FILE=/secrets/oci_api_key.pem

CERT_EXPORT_ENABLED=true
CERT_EXPORT_PATH=/export
CERT_EXPORT_PUBLIC_NAME=public.crt
CERT_EXPORT_PRIVATE_NAME=private.key
CERT_EXPORT_UID=
CERT_EXPORT_GID=
CERT_EXPORT_PUBLIC_MODE=0644
CERT_EXPORT_PRIVATE_MODE=0640
CERT_EXPORT_DEPLOY_MARKER=.oci-dns-certbot-deployed
HOST_CERT_EXPORT_PATH=/srv/oci-certbot/export
HOST_POST_RENEW_COMMAND=

# Start with a safe staging certificate.
CERTBOT_DRY_RUN=true
# Enable only to test the deploy/export hook during a dry run.
CERTBOT_RUN_DEPLOY_HOOKS=false

Prepare persistent state and put the OCI API key at /etc/oci-dns-certbot/secrets/oci_api_key.pem (mode 0600):

sudo mkdir -p /srv/oci-certbot/{etc-letsencrypt,lib-letsencrypt,log-letsencrypt,export}
sudo mkdir -p /etc/oci-dns-certbot/secrets
sudo chmod 600 /etc/oci-dns-certbot/secrets/oci_api_key.pem

Run with Podman:

sudo podman run --rm --name oci-dns-certbot   --env-file /etc/oci-dns-certbot.env   -v /srv/oci-certbot/etc-letsencrypt:/etc/letsencrypt:Z   -v /srv/oci-certbot/lib-letsencrypt:/var/lib/letsencrypt:Z   -v /srv/oci-certbot/log-letsencrypt:/var/log/letsencrypt:Z   -v /srv/oci-certbot/export:/export:Z   -v /etc/oci-dns-certbot/secrets:/secrets:ro,Z   docker.io/unsopenhub/oci-dns-certbot:1.1.1

For Docker, remove the Podman SELinux :Z suffixes.

⁠Certificate export and post-renew actions

The deploy hook writes public.crt (0644) and private.key (0640) to the mounted export directory using temporary files and atomic replacement. CERT_EXPORT_UID and CERT_EXPORT_GID must be numeric host IDs; container group names such as caddy are not portable.

On a real issuance or renewal, the image creates the marker .oci-dns-certbot-deployed after both files have been written. Run the supplied host-side helper after the container job to consume the marker and execute HOST_POST_RENEW_COMMAND, such as a service reload. This avoids mounting a container-engine socket into the certificate image.

The provided systemd service/timer and scripts/run-once.sh do this automatically. For manual runs, invoke podman/oci-dns-certbot-post-renew.sh on the host after the container exits successfully.

⁠Automation and support

Install the sample systemd service, timer, and host helper from the repository to perform a daily renewal check. Certbot renews only when the certificate is near expiry.

Complete documentation, sample configuration, and issue tracker: https://github.com/aljosavister/oci-dns-certbot⁠