Configuration of SSL Certificates

In rcstack the router component can be responsible for SSL certificates and handling SSL termination.

rcstack uses traefik project for the router component.

Please see detailed documentation about traefik SSL support here: https://doc.traefik.io/traefik/https/tls/

Enable custom traefik config

By default the shared .custom/traefik_custom/ directory is not mount into traefik. We need to enable this first, before enabling any of the below SSL certificates.

In the file .custom/docker-compose-router.override.yaml uncomment the two binds that would override defaults and allow custom code from the .custom directory

traefik:

  volumes:
    # ... other items here ...

    # THESE TWO NEEDS TO BE UNCOMMENTED
    - $PWD/.custom/traefik_custom:/etc/traefik:ro
    - $PWD/.custom/traefik_custom/dynamic:/etc/traefik_dynamic:ro

Enable file based certificates

File based certificates (including self-signed) should be places inside this .custom/traefik_custom/dynamic/certs We recommend using standard names for the .crt file (rhodecode-ssl.crt) and .key file (rhodecode-ssl.key).

e.g.

root@Ubuntu-2204 ~/rhodecode_docker # ls -la .custom/traefik_custom/certs/
total 416
drwxr-xr-x 2 root root    4096 Jan  7  2023 .
drwxr-xr-x 4 root root    4096 Jan 22  2023 ..
-rw-r--r-- 1 root root  411001 Jan  7  2023 rhodecode-ssl.crt
-rw-r--r-- 1 root root    1675 Jan  7  2023 rhodecode-ssl.key

Then those file can be enabled to act as a default certificates used in traefik.

In file .custom/traefik_custom/dynamic/traefik_dynamic_custom.yaml there a section that defines this:

tls:
  stores:
    default: {}

  # the below should be used only if acme/letsencrypt is not used, and we want a default file-based SSL certificates
  certificates:
    # first certificate in default store
    - certFile: /etc/traefik/certs/rhodecode-ssl.crt
      keyFile: /etc/traefik/certs/rhodecode-ssl.key
      stores:
        - default

Enable lets encrypt automatic certificates

In file .custom/traefik_custom/traefik.yaml

There’s a commented out section that would enable cert resolver using letsencrypt.

entryPoints:

  http:
    address: ":80"

  https:
    address: ":443"
    http:
      # default, that uses certificates from tls.certificates config in traefik_dynamic.yaml
      # Those are regular key+crt file based certificates
      tls:
        options: {}
      # Enable LE certificate wildcard domain resolver defined above
      # uncomment this to enable letsencrypt for your domains
        certResolver: letsEncryptCertResolver
        domains:
          - main: "*.rhodecode.com"
            sans:
              - "rhodecode.com"

This defines the letsEncryptCertResolver certResolver, which definition can be found above:

certificatesResolvers:
  letsEncryptCertResolver:
    acme:
      email: admin@rhodecode.com
      storage: /acme/acme.json
      dnsChallenge:
        # DNS provider used during the challenge
        # there are multiple providers available see: https://doc.traefik.io/traefik/https/acme/#providers
        provider: route53
        delayBeforeCheck: 0

Please check specific docs on traefik for more examples and required configuration for letsencrypt certificate handling

Troubleshooting

In both cases when there are some issues with SSL certificates, especially with the Letsencrypt ones. All logs and errors related to the ssl certificates would be printed to the traefik logs.

here’s how to view traefik logs with tail options and trim the results to just one last hour

./rcstack stack router logs --follow --since=1h

In case of letsencrypt the typical problems that happen are:

• acme directory permissions (installer should handle that, but still it’s important to make sure the acme storage has the right permissions)

• acme certificates credentials missing. In many cases using DNS acme resolver it’s important to make sure all credentials are correct in order to generate a proper certificate