Advanced Setup

Additional configuration options for Komodo Core and Periphery, including custom certificate authorities, OAuth/OIDC providers, and mounted config files.

Custom Certificate Authorities

In order to communicate with companion services on private networks, such as OIDC and git providers, Komodo Core and Periphery may both need to trust one or more custom CAs.

Starting in V2, Both the Komodo Core and Periphery images will automatically update-ca-certificates on startup, just mount any required root certificates inside /usr/local/share/ca-certificates:

    volumes:
      ## ... (unchanged)
      ## Mount custom root CA certificates to trust individually
      - /path/to/root_ca1.crt:/usr/local/share/ca-certificates/root_ca1.crt
      - /path/to/root_ca2.crt:/usr/local/share/ca-certificates/root_ca2.crt
      ## OR the whole folder is fine too.
      - /path/to/custom-certs:/usr/local/share/ca-certificates

OIDC / OAuth2

To enable OAuth2 login, you must create a client on the respective OAuth provider, for example GitHub or Google.

Komodo also supports self hosted OAuth2 providers like Authentik, Gitea and Keycloak.

• Komodo uses the web application login flow.
• The redirect uri is:
  • <KOMODO_HOST>/auth/github/callback for GitHub.
  • <KOMODO_HOST>/auth/google/callback for Google.
  • <KOMODO_HOST>/auth/oidc/callback for OIDC.

Authentik

Check out the Authentik integration docs.

Keycloak

• Create an OIDC client in Keycloak.
  • Note down the Client ID that you enter (e.g.: "komodo"), you will need it for Komodo configuration
  • Valid Redirect URIs: use <KOMODO_HOST>/auth/oidc/callback and substitute <KOMODO_HOST> with your Komodo url.
  • Turn Client authentication to On.
  • After you finished creating the client, open it and go to Credentials tab and copy the Client Secret
• Edit your environment variables for komodo core docker container and set the following:
  • KOMODO_OIDC_ENABLED=true
  • KOMODO_OIDC_PROVIDER=https://<your Keycloak url>/realms/master or replace master with another realm if you don't want to use the default one
  • KOMODO_OIDC_CLIENT_ID=... what you specified as Client ID
  • KOMODO_OIDC_CLIENT_SECRET=... that you copied from Keycloak

Limit Periphery IPs

If using a reverse proxy with Komodo Core, you can limit the IPs which can connect to the Periphery endpoint. For example with Caddy:

(reject-ips) {
	@externalIp not remote_ip 192.168.0.0/16 12.34.56.78/32
	respond @externalIp 403
}

komodo.example.com {
	handle /ws/periphery {
		import reject-ips
		reverse_proxy komodo-core:9120
	}
	handle {
		reverse_proxy komodo-core:9120
	}
}

:::note Your reverse proxy should set X-FORWARDED-HOST header to your Komodo Core domain, which caddy does by default. :::

Mount a Config File

If you prefer to keep sensitive information out of environment variables, you can optionally write a config file on your host, and mount it to /config/config.toml in the Komodo core container.

The configuration can also be passed as YAML or JSON. You can use it-tools to convert this TOML file to your preferred format:

• YAML: https://it-tools.tech/toml-to-yaml
• JSON: https://it-tools.tech/toml-to-json

:::info Configuration can still be passed in environment variables, and will take precedent over what is passed in the file. :::

Quick download to ./komodo/core.config.toml:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/config/core.config.toml

import RemoteCodeFile from "@site/src/components/RemoteCodeFile";

<RemoteCodeFile
	title="https://github.com/moghtech/komodo/blob/main/config/core.config.toml"
	url="https://raw.githubusercontent.com/moghtech/komodo/main/config/core.config.toml"
	language="toml"
/>