Set the webserver base URL and configure forward/reverse proxies

Configure the URL of your Kestra webserver.

Some notification services require a URL configuration to add links from alert messages. Use a full URI with a trailing / (excluding ui or api).

kestra:
  url: https://www.my-host.com/kestra/

Proxy configuration

In networking, a forward proxy acts on behalf of clients to control outbound traffic, while a reverse proxy acts on behalf of servers to control inbound traffic and may also provide features such as load balancing and SSL encryption.

A forward proxy serves as an intermediary for requests from clients seeking resources from other servers (such as the Kestra API for retrieving blueprints and plugin documentation), while a reverse proxy sits in front of one or more web servers, intercepting client requests before they reach the server.

Forward proxy configuration

In a forward proxy, the client connects to the proxy server, requesting some service (such as Kestra API) available from a different server.

To set up a proxy in your Kestra installation, adjust the micronaut.http.services.api configuration to include a proxy address, username, and password. This will allow you to make requests to the Kestra API through the proxy to fetch data for the Kestra UI, such as Blueprints. Here is how you can adjust your config.yml file to include the necessary configuration:

micronaut:
  http:
    services:
      api:
        url: https://api.kestra.io
        proxy-type: http
        proxy-address: my.company.proxy.address:port
        proxy-username: "username"
        proxy-password: "password"
        follow-redirects: true

See the Micronaut HttpClient Configuration for more details on configuring DefaultHttpClientConfiguration in your config.yml file.

Another way to authenticate is by providing micronaut.http.client.proxy-authorization: Basic <base64-encoded username:password> and micronaut.http.services.*.proxy-authorization: Basic <base64-encoded username:password>, which prevents the password from being displayed in plain text in the config file.

Reverse proxy configuration

Reverse proxies hide the server’s identity from clients and may perform tasks such as load balancing, authentication, decryption, and caching. A reverse proxy acts on behalf of the server, taking requests from the external network, and directing them to the internal server(s) that can fulfill those requests.

To display executions in real-time when hosting Kestra behind a reverse proxy, enable Server-sent events (SSE).

On some reverse proxies, such as Nginx, you need to disable buffering to enable real-time updates.

Here is a working configuration:

location / {
    proxy_pass  http://localhost:<kestra_port>;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 600s;
    proxy_redirect    off;
    proxy_set_header  Host             $http_host;
    proxy_set_header  X-Real-IP        $remote_addr;
    proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header  X-Forwarded-Protocol $scheme;

    # Needed for SSE
    proxy_buffering off;
    proxy_cache off;
}

To access Kestra via a separate context path, add the following to your Kestra startup configuration (for example, to serve the UI at mycompany.com/kestra):

micronaut:
  server:
    context-path: "/kestra"

Then, modify your above nginx configuration to the following

server {
    listen 80;
    server_name mycompany.com;

    location /kestra {
        proxy_pass  http://<kestra-hostname>:<kestra-port>/kestra;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 600s;
        proxy_redirect    off;
        proxy_set_header  Host             $http_host;
        proxy_set_header  X-Real-IP        $remote_addr;
        proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
        proxy_set_header  X-Forwarded-Protocol $scheme;

        # Needed for SSE
        proxy_buffering off;
        proxy_cache off;
    }
}