> ## Documentation Index
> Fetch the complete documentation index at: https://flipt-oci-manifest-version.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> This document describes how to configure the Flipt server.

Flipt server can be configured in two ways.

Configuration precedence is as follows:

1. [Environment Variables](#environment-variables)
2. [Configuration File](#configuration-file)

## Configuration File

The default way that Flipt is configured is with the use of a configuration file
[default.yml](https://github.com/flipt-io/flipt/blob/main/config/default.yml).

This file is read when Flipt starts up and configures several important
properties for the server.

<Tip>
  You can generate a default configuration file by running `flipt config init`
  as of v1.28.0. See the [CLI](/cli) documentation for more information.
</Tip>

The server will check in a few different locations for server configuration (in order):

1. `--config` flag as an override
2. `{{ USER_CONFIG_DIR }}/flipt/config.yml` (the `USER_CONFIG_DIR` value is based on your architecture and specified in the [Go documentation](https://pkg.go.dev/os#UserConfigDir))
3. `/etc/flipt/config/default.yml`

<Note>
  We provide both a [JSON
  schema](https://raw.githubusercontent.com/flipt-io/flipt/main/config/flipt.schema.json)
  and a [Cue
  schema](https://raw.githubusercontent.com/flipt-io/flipt/main/config/flipt.schema.cue)
  that you can use to validate your configuration file and it's properties.
</Note>

You can edit any of these properties to your liking, and on restart Flipt will
pick up the new changes.

## Environment Variables

All options in the configuration file can be overridden using environment
variables using the syntax:

```yaml
FLIPT_<SectionName>_<KeyName>
```

Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format.

<Note>
  Using environment variables to override defaults is especially helpful when
  running with Docker as described in the [Installation](/installation)
  documentation.
</Note>

Keys should be uppercase and `.` should be replaced by `_`. For example,
given these configuration settings:

```yaml
server:
  grpc_port: 9000

db:
  url: file:/var/opt/flipt/flipt.db
```

You can override them using:

```console
export FLIPT_SERVER_GRPC_PORT=9001
export FLIPT_DB_URL="postgres://postgres@localhost:5432/flipt?sslmode=disable"
```

### Multiple Values

Some configuration options can have a list of values. For example, the `cors.allowed_origins` option can have multiple origins.

In this case, you can use a space separated list of values for the environment variable override:

```console
export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
```

## Configuration Parameters

| Property                      | Description                                                   | Default              | Since   |
| ----------------------------- | ------------------------------------------------------------- | -------------------- | ------- |
| ui.default\_theme             | Sets the default UI theme for users                           | system               | v1.27.0 |
| cors.enabled                  | Enable CORS support                                           | false                | v0.7.0  |
| cors.allowed\_origins         | Sets Access-Control-Allow-Origin header on server             | "\*" (all domains)   | v0.7.0  |
| meta.check\_for\_updates      | Enable check for newer versions of Flipt on startup           | true                 | v0.17.0 |
| meta.telemetry\_enabled       | Enable anonymous telemetry data (see [Telemetry](#telemetry)) | true                 | v1.8.0  |
| meta.state\_directory         | Directory on the host to store local state                    | \$HOME/.config/flipt | v1.8.0  |
| diagnostics.profiling.enabled | Enable profiling endpoints for pprof                          | true                 | v1.29.0 |

### Logging

| Property         | Description                                                                             | Default | Since   |
| ---------------- | --------------------------------------------------------------------------------------- | ------- | ------- |
| log.level        | Level at which messages are logged (trace, debug, info, warn, error, fatal, panic)      | info    |         |
| log.grpc\_level  | Level at which gRPC messages are logged (trace, debug, info, warn, error, fatal, panic) | error   | v1.12.0 |
| log.file         | File to log to instead of STDOUT                                                        |         | v0.10.0 |
| log.encoding     | Encoding to use for logging (json, console)                                             | console | v1.12.0 |
| log.keys.time    | Structured logging key used when outputting log timestamp                               | T       | v1.18.1 |
| log.keys.level   | Structured logging key used when outputting log level                                   | L       | v1.18.1 |
| log.keys.message | Structured logging key used when outputting log message                                 | M       | v1.18.1 |

### Server

| Property                           | Description                                                                                                 | Default   | Since   |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------- | ------- |
| server.protocol                    | http or https                                                                                               | http      | v0.8.0  |
| server.host                        | The host address on which to serve the Flipt application                                                    | 0.0.0.0   |         |
| server.http\_port                  | The HTTP port on which to serve the Flipt REST API and UI                                                   | 8080      |         |
| server.https\_port                 | The HTTPS port on which to serve the Flipt REST API and UI                                                  | 443       | v0.8.0  |
| server.grpc\_port                  | The port on which to serve the Flipt GRPC server                                                            | 9000      |         |
| server.grpc\_conn\_max\_idle\_time | Maximum amount of time a GRPC connection can be idle                                                        | unlimited | v1.35.0 |
| server.grpc\_conn\_max\_age        | Maximum amount of time a GRPC connection can live                                                           | unlimited | v1.35.0 |
| server.grpc\_conn\_max\_age\_grace | Maximum amount of time a GRPC connection can live for outstanding RPCs after exceeding `grpc_conn_max_age ` | unlimited | v1.35.0 |
| server.cert\_file                  | Path to the certificate file (if protocol is set to https)                                                  |           | v0.8.0  |
| server.cert\_key                   | Path to the certificate key file (if protocol is set to https)                                              |           | v0.8.0  |

### Authentication

| Property                               | Description                                                   | Default | Since   |
| -------------------------------------- | ------------------------------------------------------------- | ------- | ------- |
| authentication.required                | Enable or disable authentication validation on requests       | false   | v1.15.0 |
| authentication.exclude.management      | Exclude authentication for /api/v1 API prefix                 | false   | v1.24.0 |
| authentication.exclude.metadata        | Exclude authentication for /meta API prefix                   | false   | v1.24.0 |
| authentication.exclude.evaluation      | Exclude authentication for /evaluation/v1 API prefix          | false   | v1.24.0 |
| authentication.session.domain          | Public domain on which Flipt instance is hosted               |         | v1.17.0 |
| authentication.session.secure          | Configures the `Secure` property on created session cookies   | false   | v1.17.0 |
| authentication.session.token\_lifetime | Configures the lifetime of the session token (login duration) | 24h     | v1.17.0 |
| authentication.session.state\_lifetime | Configures the lifetime of state parameters during OAuth flow | 10m     | v1.17.0 |
| authentication.session.csrf.key        | Secret credential used to sign CSRF prevention tokens         |         | v1.17.0 |

#### Authentication Methods: Token

| Property                                           | Description                                                      | Default | Since   |
| -------------------------------------------------- | ---------------------------------------------------------------- | ------- | ------- |
| authentication.methods.token.enabled               | Enable static token creation                                     | false   | v1.15.0 |
| authentication.methods.token.cleanup.interval      | Interval between deletion of expired tokens                      | 1h      | v1.16.0 |
| authentication.methods.token.cleanup.grace\_period | How long an expired token can exist until considered deletable   | 30m     | v1.16.0 |
| authentication.methods.token.bootstrap.token       | The static token to use for bootstrapping                        |         | v1.19.0 |
| authentication.methods.token.bootstrap.expiration  | How long after creation until the static bootstrap token expires |         | v1.19.0 |

#### Authentication Methods: OIDC

| Property                                                            | Description                                                      | Default | Since   |
| ------------------------------------------------------------------- | ---------------------------------------------------------------- | ------- | ------- |
| authentication.methods.oidc.enabled                                 | Enable OIDC authentication                                       | false   | v1.17.0 |
| authentication.methods.oidc.cleanup.interval                        | Interval between deletion of expired tokens                      | 1h      | v1.17.0 |
| authentication.methods.oidc.cleanup.grace\_period                   | How long an expired token can exist until considered deletable   | 30m     | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].issuer\_url       | Provider specific OIDC issuer URL (see your providers docs)      |         | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].client\_id        | Provider specific OIDC client ID (see your providers docs)       |         | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].client\_secret    | Provider specific OIDC client secret (see your providers docs)   |         | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].redirect\_address | Public URL on which this Flipt instance is reachable             |         | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].scopes            | Scopes to request from the provider                              |         | v1.17.0 |
| authentication.methods.oidc.providers.\[provider].use\_pkce         | Option for enabling PKCE for OIDC authentication flow            | false   | v1.26.0 |
| authentication.methods.oidc.email\_matches                          | List of email addresses (regex) of users allowed to authenticate |         | v1.24.0 |

#### Authentication Methods: GitHub

| Property                                             | Description                                                        | Default | Since   |
| ---------------------------------------------------- | ------------------------------------------------------------------ | ------- | ------- |
| authentication.methods.github.enabled                | Enable GitHub authentication                                       | false   | v1.26.0 |
| authentication.methods.github.cleanup.interval       | Interval between deletion of expired tokens                        | 1h      | v1.26.0 |
| authentication.methods.github.cleanup.grace\_period  | How long an expired token can exist until considered deletable     | 30m     | v1.26.0 |
| authentication.methods.github.client\_id             | GitHub client ID                                                   |         | v1.26.0 |
| authentication.methods.github.client\_secret         | GitHub client secret                                               |         | v1.26.0 |
| authentication.methods.github.redirect\_address      | Public URL on which this Flipt instance is reachable               |         | v1.26.0 |
| authentication.methods.github.scopes                 | Scopes to request from GitHub                                      |         | v1.26.0 |
| authentication.methods.github.allowed\_organizations | List of GitHub organizations allowed to authenticate               |         | v1.33.0 |
| authentication.methods.github.allowed\_teams         | Map of GitHub organizations to teams that users must be members of |         | v1.39.0 |

#### Authentication Methods: Kubernetes

| Property                                                        | Description                                                    | Default                                                                                      | Since   |
| --------------------------------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------- |
| authentication.methods.kubernetes.enabled                       | Enable Kubernetes service account token authentication         | false                                                                                        | v1.19.0 |
| authentication.methods.kubernetes.cleanup.interval              | Interval between deletion of expired tokens                    | 1h                                                                                           | v1.19.0 |
| authentication.methods.kubernetes.cleanup.grace\_period         | How long an expired token can exist until considered deletable | 30m                                                                                          | v1.19.0 |
| authentication.methods.kubernetes.discovery\_url                | Kubernetes API server URL for OIDC configuration discovery     | [https://kubernetes.default.svc.cluster.local](https://kubernetes.default.svc.cluster.local) | v1.19.0 |
| authentication.methods.kubernetes.ca\_path                      | Kubernetes API CA certification path                           | /var/run/secrets/kubernetes.io/serviceaccount/ca.crt                                         | v1.19.0 |
| authentication.methods.kubernetes.service\_account\_token\_path | Path to Flipt service account token                            | /var/run/secrets/kubernetes.io/serviceaccount/token                                          | v1.19.0 |

#### Authentication Methods: JWT

| Property                                              | Description                                         | Default | Since   |
| ----------------------------------------------------- | --------------------------------------------------- | ------- | ------- |
| authentication.methods.jwt.enabled                    | Enable JWT authentication                           | false   | v1.35.0 |
| authentication.methods.jwt.jwks\_url                  | URL to retrieve JWKS for JWT validation             |         | v1.35.0 |
| authentication.methods.jwt.public\_key\_file          | Path to public key file for JWT validation          |         | v1.35.0 |
| authentication.methods.jwt.validate\_claims.issuer    | The issuer claim to validate on JWT tokens          |         | v1.35.0 |
| authentication.methods.jwt.validate\_claims.audiences | The audience claim (list) to validate on JWT tokens |         | v1.35.0 |

### Database

| Property                         | Description                                                         | Default                             | Since                  |
| -------------------------------- | ------------------------------------------------------------------- | ----------------------------------- | ---------------------- |
| db.url                           | URL to access Flipt database                                        | file:/(OS Dependent)/flipt/flipt.db | v1.26.0 \*OS Dependent |
| db.protocol                      | Protocol for Flipt database (URL takes precedence)                  |                                     | v0.18.0                |
| db.host                          | Host to access Flipt database (URL takes precedence)                |                                     | v0.18.0                |
| db.port                          | Port to access Flipt database (URL takes precedence)                |                                     | v0.18.0                |
| db.name                          | Name of Flipt database (URL takes precedence)                       |                                     | v0.18.0                |
| db.user                          | User to access Flipt database (URL takes precedence)                |                                     | v0.18.0                |
| db.password                      | Password to access Flipt database (URL takes precedence)            |                                     | v0.18.0                |
| db.max\_idle\_conn               | The maximum number of connections in the idle connection pool       | 2                                   | v0.17.0                |
| db.max\_open\_conn               | The maximum number of open connections to the database              | unlimited                           | v0.17.0                |
| db.conn\_max\_lifetime           | Sets the maximum amount of time in which a connection can be reused | unlimited                           | v0.17.0                |
| db.prepared\_statements\_enabled | Enable or disable prepared statements for database queries          | true                                | v1.23.1                |

### Storage

| Property           | Description                                               | Default  | Since   |
| ------------------ | --------------------------------------------------------- | -------- | ------- |
| storage.type       | The type of storage to use (database, local, git, object) | database | v1.25.0 |
| storage.read\_only | Enable read-only mode for storage                         | false    | v1.25.0 |

#### Storage Local

| Property           | Description                             | Default | Since   |
| ------------------ | --------------------------------------- | ------- | ------- |
| storage.local.path | The path to the local storage directory |         | v1.25.0 |

#### Storage Git

| Property                                                   | Description                                                 | Default | Since   |
| ---------------------------------------------------------- | ----------------------------------------------------------- | ------- | ------- |
| storage.git.repository                                     | The URL of the git repository to use                        |         | v1.25.0 |
| storage.git.ref                                            | The git ref to use                                          | main    | v1.25.0 |
| storage.git.poll\_interval                                 | The interval to poll the git repository and ref for changes | 30s     | v1.25.0 |
| storage.git.authentication.basic.username                  | The username to use for basic authentication                |         | v1.25.0 |
| storage.git.authentication.basic.password                  | The password to use for basic authentication                |         | v1.25.0 |
| storage.git.authentication.token                           | The access token to use for authentication                  |         | v1.25.0 |
| storage.git.authentication.ssh.password                    | Password used to generate the SSH key pair                  |         | v1.30.0 |
| storage.git.authentication.ssh.private\_key\_path          | Path to private key on the filesystem                       |         | v1.30.0 |
| storage.git.authentication.ssh.private\_key\_bytes         | (Alternative) Raw private key bytes                         |         | v1.30.0 |
| storage.git.authentication.ssh.insecure\_ignore\_host\_key | Skip verifying the known hosts key (avoid in production)    | false   | v1.30.0 |

#### Storage Object

| Property            | Description                            | Default | Since   |
| ------------------- | -------------------------------------- | ------- | ------- |
| storage.object.type | The type of object storage to use (s3) | s3      | v1.25.0 |

##### Storage Object: S3

| Property                         | Description                                 | Default | Since   |
| -------------------------------- | ------------------------------------------- | ------- | ------- |
| storage.object.s3.region         | The AWS region to use for S3 object storage |         | v1.25.0 |
| storage.object.s3.bucket         | The S3 bucket to use for object storage     |         | v1.25.0 |
| storage.object.s3.prefix         | The S3 prefix to use for object storage     |         | v1.25.0 |
| storage.object.s3.endpoint       | The S3 endpoint to use for object storage   |         | v1.25.0 |
| storage.object.s3.poll\_interval | The interval to poll S3 for changes         | 30s     | v1.25.0 |

#### Storage OCI

| Property                            | Description                                           | Default                | Since   |
| ----------------------------------- | ----------------------------------------------------- | ---------------------- | ------- |
| storage.oci.repository              | The target bundle repository (with optional registry) |                        | v1.31.0 |
| storage.oci.authentication.username | The username to use for authentication                |                        | v1.31.0 |
| storage.oci.authentication.password | The password to use for authentication                |                        | v1.31.0 |
| storage.oci.bundles\_directory      | The directory in which to store local bundles         | \$config/flipt/bundles | v1.31.0 |
| storage.oci.poll\_interval          | The interval to poll the registry for changes         | 30s                    | v1.31.0 |
| storage.oci.manifest\_verison       | The OCI manifest version to use                       | 1.1                    | v1.39.1 |

### Cache

| Property      | Description                                             | Default | Since   |
| ------------- | ------------------------------------------------------- | ------- | ------- |
| cache.enabled | Enable caching of data                                  | false   | v1.10.0 |
| cache.ttl     | Time to live for cached data                            | 60s     | v1.10.0 |
| cache.backend | The backend to use for caching (options: memory, redis) | memory  | v1.10.0 |

#### Cache: Memory

| Property                        | Description                                                          | Default | Since   |
| ------------------------------- | -------------------------------------------------------------------- | ------- | ------- |
| cache.memory.eviction\_interval | Interval at which expired items are evicted from the in-memory cache | 5m      | v0.12.0 |

#### Cache: Redis

| Property                          | Description                                     | Default   | Since   |
| --------------------------------- | ----------------------------------------------- | --------- | ------- |
| cache.redis.host                  | Host to access the Redis database               | localhost | v1.10.0 |
| cache.redis.port                  | Port to access the Redis database               | 6379      | v1.10.0 |
| cache.redis.db                    | Redis database to use                           | 0         | v1.10.0 |
| cache.redis.password              | Password to access the Redis database           |           | v1.10.0 |
| cache.redis.require\_tls          | Require TLS to access the Redis database        | false     | v1.25.0 |
| cache.redis.pool\_size            | Max number of socket connections per CPU        | 10        | v1.25.0 |
| cache.redis.min\_idle\_conn       | Minimum number of idle connections in the pool  | 0         | v1.25.0 |
| cache.redis.conn\_max\_idle\_time | Maximum amount of time a connection can be idle | 30m       | v1.25.0 |
| cache.redis.net\_timeout          | Network timeout for Redis connections           | 0         | v1.25.0 |

### Audit Events

| Property                   | Description                                        | Default  | Since   |
| -------------------------- | -------------------------------------------------- | -------- | ------- |
| audit.buffer.capacity      | Max capacity of buffer to send events to sinks     | 2        | v1.21.0 |
| audit.buffer.flush\_period | Duration to wait before sending events to sinks    | 2m       | v1.21.0 |
| audit.events               | Type of events user would like to receive on sinks | \["*:*"] | v1.27.0 |

#### Audit Events: Log File

| Property                | Description                                                              | Default | Since   |
| ----------------------- | ------------------------------------------------------------------------ | ------- | ------- |
| audit.sinks.log.enabled | Enable log file sink                                                     | false   | v1.21.0 |
| audit.sinks.log.file    | File path to write audit events to. Required if log file sink is enabled |         | v1.21.0 |

#### Audit Events: Webhook

| Property                                   | Description                                                        | Default | Since   |
| ------------------------------------------ | ------------------------------------------------------------------ | ------- | ------- |
| audit.sinks.webhook.enabled                | Enable webhook sink                                                | false   | v1.27.0 |
| audit.sinks.webhook.url                    | URL to send audit events to                                        |         | v1.27.0 |
| audit.sinks.webhook.signing\_secret        | Signing secret to use for verification of origin on webhook server |         | v1.27.0 |
| audit.sinks.webhook.max\_backoff\_duration | Max exponential backoff duration for sending webhook upon failure  | 15s     | v1.27.0 |
| audit.sinks.webhook.templates\[]           | List of webhook templates for Flipt to send audit events to        |         | v1.28.0 |

### Analytics

| Property                       | Description                                     | Default | Since   |
| ------------------------------ | ----------------------------------------------- | ------- | ------- |
| analytics.buffer.flush\_period | Duration to wait before sending events to sinks | 10s     | v1.37.0 |

#### Analytics: Clickhouse

| Property                             | Description                         | Default | Since   |
| ------------------------------------ | ----------------------------------- | ------- | ------- |
| analytics.storage.clickhouse.enabled | Enable Clickhouse support           | false   | v1.37.0 |
| analytics.storage.clickhouse.url     | URL to connect to clickhouse server |         | v1.37.0 |

### Tracing

| Property         | Description                                | Default | Since   |
| ---------------- | ------------------------------------------ | ------- | ------- |
| tracing.enabled  | Enable tracing support                     | false   | v1.18.2 |
| tracing.exporter | The exporter to use (jaeger, zipkin, otlp) | jaeger  | v1.18.2 |

#### Tracing: Jaeger

| Property            | Description                              | Default   | Since   |
| ------------------- | ---------------------------------------- | --------- | ------- |
| tracing.jaeger.host | The UDP host destination to report spans | localhost | v0.17.0 |
| tracing.jaeger.port | The UDP port destination to report spans | 6831      | v0.17.0 |

#### Tracing: Zipkin

| Property                | Description                             | Default                                                                  | Since   |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------ | ------- |
| tracing.zipkin.endpoint | The Zipkin API endpoint to report spans | [http://localhost:9411/api/v2/spans](http://localhost:9411/api/v2/spans) | v1.18.2 |

#### Tracing: OTLP

| Property              | Description                                                        | Default               | Since   |
| --------------------- | ------------------------------------------------------------------ | --------------------- | ------- |
| tracing.otlp.endpoint | The OTLP receiver address (supports: grpc, http, https)            | grpc://localhost:4317 | v1.18.2 |
| tracing.otlp.headers  | Additional headers to send with OTLP requests (map\[string]string) |                       | v1.28.0 |

## Deprecations

From time to time configuration options will need to be deprecated and
eventually removed. Deprecated configuration options will be removed after \~6
months from the time they were deprecated.

All deprecated configuration options will be removed from the documentation,
however, they will still work as expected until they're removed. A warning will
be logged in the Flipt logs when a deprecated configuration option is used.

All deprecated options are listed in the [DEPRECATIONS](https://github.com/flipt-io/flipt/blob/main/DEPRECATIONS.md) file
in the Flipt repository as well as the [CHANGELOG](https://github.com/flipt-io/flipt/blob/main/CHANGELOG.md).