> ## Documentation Index
> Fetch the complete documentation index at: https://flipt-clickhouse-docs.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: 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 |

### 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).