Reverse Proxy

Logchef serves the web UI and the API from one HTTP port (8125 by default). You can put a reverse proxy in front of it to terminate TLS, and serve it on its own domain (https://logs.example.com/) or under a subpath of an existing domain (https://example.com/logchef/).

On its own domain

Forward every request to Logchef. No extra Logchef configuration is necessary.

server {
  listen 443 ssl;
  server_name logs.example.com;

  location / {
    proxy_pass http://127.0.0.1:8125;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Set server.frontend_url to https://logs.example.com so that share links use the public URL.

Under a subpath

To serve Logchef under a subpath, do these two steps:

Tell Logchef its public URL, including the subpath.
Configure the proxy to remove the subpath before it forwards the request.

Logchef itself always serves from /. When a request comes in, the proxy changes /logchef/logs/explore to /logs/explore. Logchef reads the subpath from server.frontend_url and uses it to build the links it sends back to the browser.

Configure Logchef

[server]
# Public URL of the web UI, including the subpath.
frontend_url = "https://example.com/logchef"

[oidc]
# Only when you use OIDC. Register the same URL with your OIDC provider.
redirect_url = "https://example.com/logchef/api/v1/auth/callback"

With frontend_url set:

The web UI loads its assets and calls the API under /logchef/.
Login redirects and share links point to https://example.com/logchef/....
Session cookies use Path=/logchef. The browser does not send them to other applications on the same domain.

Logchef reads frontend_url when it starts. Restart Logchef after you change it. The value in Administration → System Settings → Server takes precedence over config.toml when it is not empty.

For alert notifications, set Frontend URL under Administration → System Settings → Alerts to the same URL (https://example.com/logchef). Alert links then open under the subpath.

nginx

location /logchef/ {
  # The trailing slash in proxy_pass removes the /logchef prefix.
  proxy_pass http://127.0.0.1:8125/;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header X-Forwarded-Proto $scheme;
}

nginx redirects /logchef to /logchef/.

Caddy

example.com {
  redir /logchef /logchef/
  # handle_path removes the /logchef prefix.
  handle_path /logchef/* {
    reverse_proxy 127.0.0.1:8125
  }
}

Traefik

http:
  routers:
    logchef:
      rule: "Host(`example.com`) && PathPrefix(`/logchef`)"
      middlewares: [logchef-strip-prefix]
      service: logchef
  middlewares:
    logchef-strip-prefix:
      stripPrefix:
        prefixes: ["/logchef"]
  services:
    logchef:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:8125"

A PathPrefix rule without the stripPrefix middleware does not work. Logchef does not serve routes under /logchef/.

Other proxies

Any proxy works if it removes the subpath before it forwards the request. To make sure that the proxy is correct, open https://example.com/logchef/logs/explore directly. The login page must load. A blank page means that the proxy does not remove the subpath.

CLI

Logchef OAuth does not support a subpath, because server.public_url must be an origin only. For the browser sign-in of the CLI (logchef auth) and for the /mcp endpoint, serve Logchef on its own domain.

Under a subpath, use an API token and include the subpath in the server URL:

logchef --server https://example.com/logchef --token "$LOGCHEF_AUTH_TOKEN" whoami

OAuth and MCP

When Logchef OAuth is on and one host serves everything, the proxy must pass these paths to Logchef without a rewrite:

/oauth/*
/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp
/mcp

Set server.public_url to the exact address that clients use. Keep the Host header and the https scheme as the client sent them. The OAuth issuer must equal that address.

Split UI and API hosts

You can put the web UI behind an SSO proxy and give CLIs and agents a second host that does not use the proxy. For example, logchef.example.com is the UI host, and logchef-api.example.com is the API host. Both hosts point to the same Logchef process.

[server]
public_url = "https://logchef-api.example.com"
browser_url = "https://logchef.example.com"
frontend_url = "https://logchef.example.com"

[auth.oauth]
enabled = true

public_url is the API host. It is the OAuth issuer, and it serves the tokens and /mcp. browser_url is the UI host. It serves the pages where the user signs in and approves. Refer to Split deployments for the full list of what each setting controls.

The UI host (logchef.example.com) must pass these paths to Logchef. The SSO proxy sits in front of them:

/oauth/authorize
/oauth/consent, which is a page of the web UI
/api/v1/oauth/requests/*
/api/v1/me/connected-apps*
the login routes, and the rest of the web UI

The API host (logchef-api.example.com) must serve these paths with no SSO proxy in front, because CLIs and agents cannot complete an SSO prompt:

/.well-known/oauth-authorization-server
/.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp
/oauth/token and /oauth/revoke
/mcp
/api/v1/*

If you do not set browser_url, one host serves all of these paths.

Live tail

Live tail uses Server-Sent Events. Logchef sends the X-Accel-Buffering: no header, which stops nginx from buffering the stream. It also sends a heartbeat every 15 seconds, so the default proxy read timeouts do not close an idle stream. Caddy and Traefik stream the events without extra configuration.

Client IP

To make the proxy’s X-Forwarded-For header available for client-IP features such as per-IP rate limiting, set server.trusted_proxies to the proxy’s address. Refer to Configuration.