> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubestacks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Server configuration

> The environment variables KubeStacks reads when it runs as a server, and the addresses it answers.

The Helm chart sets these from its [values](/server/helm-values). They're for running the image another way, such as [with Docker](/server/docker), and for the few settings the chart has no value for, which you can set with `extraEnv`.

KubeStacks reads them when it starts. One that doesn't make sense stops it, and its log says which and why.

## Where it runs

<ResponseField name="KUBESTACKS_PORT" type="number" default="8080">
  The port to listen on. `0` picks any free port, and the log says which.
</ResponseField>

<ResponseField name="KUBESTACKS_ADDRESS" type="string">
  The address to listen on: every interface unless set.
</ResponseField>

<ResponseField name="KUBESTACKS_URL" type="string">
  The address people open it at, like `https://kubestacks.example.com`. Single sign-on needs it. With `https:`, cookies are sent over HTTPS only.
</ResponseField>

<ResponseField name="KUBESTACKS_BASE_PATH" type="string" default="/">
  Where it is below that address, like `/kubestacks`.
</ResponseField>

## The cluster it shows

<ResponseField name="KUBESTACKS_CLUSTER_NAME" type="string">
  What it calls the cluster: `in-cluster` (or the kubeconfig's context) unless set.
</ResponseField>

<ResponseField name="KUBECONFIG" type="string">
  A kubeconfig to show a cluster from, instead of the cluster KubeStacks runs in.
</ResponseField>

<ResponseField name="KUBESTACKS_CONTEXT" type="string">
  The kubeconfig's context to show: its current context unless set.
</ResponseField>

<ResponseField name="KUBESTACKS_SERVICE_ACCOUNT_DIR" type="string" default="/var/run/secrets/kubernetes.io/serviceaccount">
  Where the pod's service account token and CA certificate are, inside a cluster.
</ResponseField>

## Sign-in

<ResponseField name="KUBESTACKS_AUTH" type="string" default="token">
  `token`, `oidc` or `proxy`. See [Ways to sign in](/server/overview#ways-to-sign-in).
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_ISSUER" type="string">
  The OpenID Connect provider's issuer URL. Required with `oidc`.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_CLIENT_ID" type="string">
  KubeStacks' client ID at the provider. Required with `oidc`.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_CLIENT_SECRET" type="string">
  The client's secret. Unset for a public client.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_SCOPES" type="string" default="openid email profile">
  The scopes to ask for, separated by spaces.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_USERNAME_CLAIM" type="string" default="email">
  The ID token claim that names people.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_GROUPS_CLAIM" type="string" default="groups">
  The ID token claim that lists their groups.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_PROVIDER_NAME" type="string" default="single sign-on">
  The provider's name on the sign-in button: **Sign in with** this.
</ResponseField>

<ResponseField name="KUBESTACKS_OIDC_FORWARD_TOKEN" type="string">
  `id` or `access`: pass people's own token on (the API server must trust the provider) instead of impersonating them.
</ResponseField>

<ResponseField name="KUBESTACKS_PROXY_USER_HEADER" type="string" default="X-Forwarded-User">
  The header a proxy names people in.
</ResponseField>

<ResponseField name="KUBESTACKS_PROXY_GROUPS_HEADER" type="string" default="X-Forwarded-Groups">
  The header a proxy lists their groups in, separated by commas.
</ResponseField>

<ResponseField name="KUBESTACKS_PROXY_SIGN_OUT_URL" type="string">
  Where signing out of the proxy is.
</ResponseField>

<ResponseField name="KUBESTACKS_USERNAME_PREFIX" type="string">
  Put before impersonated users' names.
</ResponseField>

<ResponseField name="KUBESTACKS_GROUPS_PREFIX" type="string">
  Put before impersonated groups' names.
</ResponseField>

<ResponseField name="KUBESTACKS_SESSION_HOURS" type="number" default="12">
  How long sessions last, in hours: at most 168, a week.
</ResponseField>

<ResponseField name="KUBESTACKS_HEARTBEAT_SECONDS" type="number" default="30">
  How often pages' connections are checked, in seconds, at most 3600. Keep it shorter than the idle timeout of the proxies in front of KubeStacks.
</ResponseField>

## What people can do

<ResponseField name="KUBESTACKS_READ_ONLY" type="boolean" default="false">
  `true` or `1`: nobody changes anything through KubeStacks.
</ResponseField>

<ResponseField name="KUBESTACKS_METRICS_SOURCE" type="string" default="auto">
  Where usage history comes from unless people choose: `auto`, `off`, or `namespace/service:port`, with a path after it for vmselect (`vm/vmselect:8481/select/0/prometheus`).
</ResponseField>

<ResponseField name="KUBESTACKS_ALLOW_PRIVATE_CHARTS" type="boolean" default="false">
  `true` or `1`: charts may come from private network addresses.
</ResponseField>

<ResponseField name="KUBESTACKS_ARTIFACT_HUB_URL" type="string" default="https://artifacthub.io">
  Where to search for charts.
</ResponseField>

<ResponseField name="KUBESTACKS_VIEWS_DIR" type="string" default="/etc/kubestacks/views">
  Where the views everyone sees are.
</ResponseField>

<ResponseField name="KUBESTACKS_HELM" type="string" default="/usr/local/bin/helm">
  The helm to run: the one in the image unless set.
</ResponseField>

## Large clusters and slow API servers

These work the same as in the desktop app, and the chart has no values for them: set them with `extraEnv`.

<ResponseField name="KUBESTACKS_MAX_LIST_ITEMS" type="number" default="5000">
  The most objects a list loads. Lists are fetched in chunks of 500.
</ResponseField>

<ResponseField name="KUBESTACKS_REQUEST_TIMEOUT_MS" type="number" default="20000">
  How long the API server has to answer, in milliseconds.
</ResponseField>

```yaml values.yaml theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
extraEnv:
  - name: KUBESTACKS_MAX_LIST_ITEMS
    value: '10000'
  - name: KUBESTACKS_REQUEST_TIMEOUT_MS
    value: '45000'
```

## Addresses it answers

All of these are below the base path.

| Address | What it's for |
| - | - |
| `GET healthz` | Health checks: answers `200 ok` while KubeStacks runs. |
| `auth/callback` | Where your OpenID Connect provider sends people back. Register it as the redirect URI. |
| `api/socket` | Each page's WebSocket. Proxies in front of KubeStacks must pass WebSockets here. |

Every other address is KubeStacks' page and its files.

<Columns cols={2}>
  <Card title="Helm values" icon="sliders-horizontal" href="/server/helm-values">
    The chart's settings, which set these for you.
  </Card>

  <Card title="Run it with Docker" icon="container" href="/server/docker">
    Use these to run the image outside Kubernetes.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.