docs/source/configuration/ssl-certificates.rst

.. _configuration-of-ssl-certificates:

=================================
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 :file:`.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 :file:`.custom/docker-compose-router.override.yaml` uncomment the two binds that would override defaults
and allow custom code from the `.custom` directory


.. code-block:: yaml

      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 :file:`.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.

.. code-block:: bash

    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 :file:`.custom/traefik_custom/dynamic/traefik_dynamic_custom.yaml` there a section that defines this:


.. code-block:: yaml

    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 :file:`.custom/traefik_custom/traefik.yaml`

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


.. code-block:: yaml


    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:

.. code-block:: yaml

    certificatesResolvers:
      letsEncryptCertResolver:
        acme:
          email: [e-mail]
          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


.. code-block:: bash

    ./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