Ontopic Docs

# Setting up HTTPS

# Docker-compose with Caddy

Caddy (opens new window) is a modern, open-source web server that simplifies the process of setting up and managing HTTPS. In this document, we'll guide you on how to use the Caddy Docker image to handle HTTPS with Ontopic Suite.

# Prerequisites

Before you begin, ensure that you have Docker installed on your system.

The simplest way to enable HTTPS with Caddy is to use the provided docker-compose.caddy.yml file, which is preconfigured to work with Ontopic Suite out of the box.

# Configure the Virtual Host

In your .env file, set the VIRTUAL_HOST variable to your domain name:

VIRTUAL_HOST=yourdomain.com

Replace yourdomain.com with your actual domain name.

# Start Ontopic Suite with Caddy

Run the following command to start Ontopic Suite with Caddy:

docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d

This will start all services including Caddy, which will automatically handle HTTPS certificates and reverse proxy configuration.

# Access Ontopic Suite

Visit Ontopic Suite in a web browser using the HTTPS protocol (e.g., https://yourdomain.com), and Caddy will automatically obtain and manage TLS certificates for you.

# Custom Caddy Setup (Advanced)

If you need more customization beyond the default configuration, you can modify the docker-compose.caddy.yml to use the vanilla Caddy image and create your own Caddyfile.

# Create a Custom Caddyfile

Create a file called Caddyfile (no extension) in your root directory. The Caddyfile is the configuration file for Caddy, where you can define your site configurations. Here is a simple example:

yourdomain.com {
    header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    reverse_proxy 172.17.0.1:8081
}

Replace yourdomain.com with your actual domain and update the reverse_proxy directive with the address and port of Ontopic Suite.

If your server is not accessible from the Internet, more configuration is needed.

Caddy is highly customizable, and you can modify the Caddyfile to suit your specific needs. Refer to the Caddy documentation (opens new window) for more information.

# Override the Caddy Service in Docker Compose

Create a file called docker-compose.caddy-custom.yml based on docker-compose.caddy.yml, but using the vanilla Caddy's Docker image and mounting your custom Caddyfile:

services:
  caddy:
    image: caddy:2.7-alpine
    restart: unless-stopped
    ports:
      - 80:80
      - 443:443
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ${CADDY_DATA_DIR:-caddy-data}:/data
    networks:
      - application
  nginx:
    environment:
      VIRTUAL_PORT: 80
  identity-service:
    environment:
      ONTOPIC_IDENTITY_SERVICE_COOKIE_SECURE: 'true'
  git-mirror:
    environment:
      PROTOCOL: https
      GITEA_MIRROR_PORT: 80
      HTTP_PORT: 80
      COOKIE_SECURE: 'true'
volumes:
  caddy-data:

# Start Ontopic Suite with Custom Caddy

Run the following command to start Ontopic Suite with your custom Caddy configuration:

docker compose -f docker-compose.yml -f docker-compose.caddy-custom.yml up -d

This uses your custom configuration instead of the default docker-compose.caddy.yml.

# Kubernetes

To enable HTTPS in your Kubernetes deployment, you need to provide a TLS certificate stored in a Kubernetes secret named ontopic-tls.

We recommend using cert-manager (opens new window) to automatically obtain and renew TLS certificates from Let's Encrypt.

# Install cert-manager

First, add the Jetstack Helm repository:

helm repo add jetstack https://charts.jetstack.io
helm repo update

Next, install cert-manager with its Custom Resource Definitions (CRDs):

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Verify the installation by checking that all cert-manager pods are running:

kubectl get pods -n cert-manager

All pods should show a Running status before proceeding.

# Configure the ClusterIssuer

A ClusterIssuer is a cert-manager resource that defines how to obtain certificates. The Ontopic Suite Helm chart can automatically create a Let's Encrypt ClusterIssuer for you.

Domain Must Be Publicly Accessible

The TLS certificate procedure uses the HTTP-01 challenge (opens new window) to prove control over the domain name. Your domain name must already be assigned to your public IP address.

Add the following configuration to your values.yaml:

clusterIssuer:
  enabled: true
  email: <YOUR_EMAIL>            # Required: your email for Let's Encrypt notifications
  ingressClass: <INGRESS_CLASS>  # Your ingress controller class (e.g., traefik or azure-application-gateway)

Replace <YOUR_EMAIL> with your email address (required by Let's Encrypt for certificate expiration notifications) and <INGRESS_CLASS> with your ingress controller's class name.

# Configure ingress for TLS

Update your ingress configuration in values.yaml to enable TLS:

ingress:
  # ...
  tls: true
  secretName: ontopic-tls
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod

# Additional ingress controller configurations

For Traefik, add these annotations:

    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"

For Azure Application Gateway Ingress Controller (AGIC), add this annotation:

    appgw.ingress.kubernetes.io/ssl-redirect: "true"

# Apply changes

To apply changes, stop and start Ontopic Suite again.

← Access control policies →