Skip to main content
Version: Next

SSL

Woodpecker supports two ways of enabling SSL communication. You can either use Let's Encrypt to get automated SSL support with renewal or provide your own SSL certificates.

Let's Encrypt​

Woodpecker supports automated SSL configuration and updates using Let's Encrypt.

You can enable Let's Encrypt by making the following modifications to your server configuration:

WOODPECKER_LETS_ENCRYPT=true
WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld

Note that Woodpecker uses the hostname from the WOODPECKER_HOST environment variable when requesting certificates. For example, if WOODPECKER_HOST=https://example.com is set the certificate is requested for example.com. To receive emails before certificates expire Let's Encrypt requires an email address. You can set it with WOODPECKER_LETS_ENCRYPT_EMAIL=ssl-admin@example.tld.

The SSL certificates are stored in $HOME/.local/share/certmagic for binary versions of Woodpecker and in /var/lib/woodpecker for the Container versions of it. You can set a custom path by setting XDG_DATA_HOME if required.

Once enabled you can visit the Woodpecker UI with http and the HTTPS address. HTTP will be redirected to HTTPS.

Certificate Cache​

Woodpecker writes the certificates to /var/lib/woodpecker/certmagic/.

Certificate Updates​

Woodpecker uses the official Go acme library which will handle certificate upgrades. There should be no addition configuration or management required.

SSL with own certificates​

Woodpecker supports SSL configuration by mounting certificates into your container.

WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key

Certificate Chain​

The most common problem encountered is providing a certificate file without the intermediate chain.

LoadX509KeyPair reads and parses a public/private key pair from a pair of files. The files must contain PEM encoded data. The certificate file may contain intermediate certificates following the leaf certificate to form a certificate chain.

Certificate Errors​

SSL support is provided using the ListenAndServeTLS function from the Go standard library. If you receive certificate errors or warnings please examine your configuration more closely.

Running in containers​

Update your configuration to expose the following ports:

docker-compose.yaml
 version: '3'

 services:
   woodpecker-server:
     [...]
     ports:
+      - 80:80
+      - 443:443
       - 9000:9000

Update your configuration to mount your certificate and key:

docker-compose.yaml
 version: '3'

 services:
   woodpecker-server:
     [...]
     volumes:
+      - /etc/certs/woodpecker.example.com/server.crt:/etc/certs/woodpecker.example.com/server.crt
+      - /etc/certs/woodpecker.example.com/server.key:/etc/certs/woodpecker.example.com/server.key

Update your configuration to provide the paths of your certificate and key:

docker-compose.yaml
 version: '3'

 services:
   woodpecker-server:
     [...]
     environment:
+      - WOODPECKER_SERVER_CERT=/etc/certs/woodpecker.example.com/server.crt
+      - WOODPECKER_SERVER_KEY=/etc/certs/woodpecker.example.com/server.key