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

# Configuration

> Reference for Sequin configuration options. Explore advanced settings for clustering, memory management, and authentication.

## Environment variables

The standard [Docker Compose file](https://raw.githubusercontent.com/sequinstream/sequin/main/docker/docker-compose.yaml) includes sane defaults for [getting started quickly](/running-sequin).

You can configure Sequin by setting environment variables.

<Info>
  To see the file that loads and uses these environment variables, see [config/runtime.exs](https://github.com/sequinstream/sequin/blob/main/config/runtime.exs).
</Info>

### General configuration

* `SERVER_PORT`: Server port number (default: 7376)
  * This is the port that Sequin will listen on for incoming connections. It's the port for both the web console as well as the API.
* `SERVER_HOST`: Host name for the server
  * If you're hosting Sequin at a custom domain, you should set this to that domain.
* `SERVER_CHECK_ORIGIN`: Enable origin checking (default: `false`)
  * If you're hosting Sequin at a public URL, you should set this to `true` and set `SERVER_HOST` to your public domain. This will ensure that Sequin only serves requests from origins matching `SERVER_HOST`. e.g. if your app is hosted at `https://sequin.example.com`, you should set `SERVER_HOST` to `sequin.example.com` and `SERVER_CHECK_ORIGIN` to `true`.
* `LOG_LEVEL`: Sets application logging verbosity (default: `info`)
  * Valid values: `error`, `warning`, `notice`, `info`, `debug`
* `SEQUIN_LOG_FORMAT`: Sets the log format (default: `console`)
  * `console` outputs logs to the console in a human-readable format.
  * `datadog_json` outputs logs in JSON format, which is compatible with Datadog's logging format.

### Configuration file

You can provide a YAML configuration file to Sequin. This configuration file will upsert databases, sinks, and other resources on boot.

* `CONFIG_FILE_PATH`: Path to configuration file
* `CONFIG_FILE_YAML`: YAML configuration content (base64 encoded)
  * If it's easier, you can provide the YAML directly as an environment variable. The YAML file must be base64 encoded.

### Postgres configuration

Sequin uses a Postgres database to store state, such as your database connections and sinks. This database is separate from the Postgres databases you stream from (and can configure in [`sequin.yaml`](/reference/sequin-yaml#database-configuration)). It is recommended to give Sequin its own logical database, though it may reside on the same physical Postgres database as your source databases.

* `PG_URL`: Complete Postgres connection URL (alternative to individual PG\_\* variables below)
  * (e.g. `postgres://sequin:password@localhost:5432/sequin`)
* `PG_PORT`: Postgres port number (default: 5432)
* `PG_HOSTNAME`: Postgres host address
* `PG_DATABASE`: Database name
* `PG_USERNAME`: Database user
* `PG_PASSWORD`: Database password
* `PG_IPV6`: Enable IPv6 support (default: false)
* `PG_SSL`: Enable SSL for Postgres connection (default: false)
* `PG_POOL_SIZE`: Database connection pool size (default: 10)

#### `PG_POOL_SIZE`

The `PG_POOL_SIZE` variable controls the maximum number of concurrent connections that Sequin will maintain to Postgres. For higher throughput on larger Postgres instances, you should increase this value.

### Runtime configuration

* `DEFAULT_WORKERS_PER_SINK`: Sets a global default for the number of concurrent workers to assign to each sink. If not set, Sequin will use a default based on the number of CPU cores. You may want to set higher if you have high-latency destinations, like slow webhook endpoints. Must be an integer >= 1.
* `BACKFILL_MAX_PENDING_MESSAGES`: When backfilling, the maximum number of pending messages to accumulate in the sink's outbox before pausing the backfill. When messages start draining to the sink, the backfill will automatically resume. The default is 1M messages.
* `MAX_MEMORY_MB`: Maximum memory limit in megabytes
  * If not set, Sequin will use available system memory
  * Example: `2048` for 2GB limit
* `MEMORY_BUFFER_PERCENT`: Percentage of memory to reserve as buffer (default: 20)
  * Sequin will use (100 - MEMORY\_BUFFER\_PERCENT)% of either the system memory or MAX\_MEMORY\_MB
  * Example: `20` reserves 20% as buffer, using 80% of available memory

<Warning>
  Sequin will actively work to keep memory usage below these configured limits. While these settings help manage memory utilization, there is [ongoing development](https://github.com/sequinstream/sequin/issues/930) to further optimize memory usage.
</Warning>

<Note>
  If you're running Sequin outside of our provided Docker images and on a non-Linux system, you must manually set `MAX_MEMORY_MB`.
</Note>

### Redis configuration

* `REDIS_URL`: Redis connection URL (required)
  * Format: `redis://localhost:6379` or `rediss://localhost:6379`
  * Using `rediss://` automatically enables SSL/TLS
  * Using `redis://localhost:6379/1` will connect to Redis database 1
  * Using `redis://username:password@localhost:6379` will authenticate as `username`
    * Username is required - use `default` if you are not using redis users
* `REDIS_TLS`: Enable SSL/TLS for Redis connection (optional)
  * Valid values: `"true"`, `"1"`
  * Default: disabled
* `REDIS_IPV6`: Enable IPv6 support (optional)
  * Valid values: `"true"` or `"1"` to enable
  * Default: disabled
* `REDIS_POOL_SIZE`: Number of Redis connections in the pool (optional)
  * Must be a positive integer
  * Default: 5
* `REDIS_TLS_CA_CERT_FILE`: Path to CA certificate file for server verification
* `REDIS_TLS_CLIENT_CERT_FILE`: Path to client certificate file (for mTLS)
  * Required for mutual TLS authentication
  * Must be used together with `REDIS_TLS_CLIENT_KEY_FILE`
* `REDIS_TLS_CLIENT_KEY_FILE`: Path to client private key file (for mTLS)
  * Required for mutual TLS authentication
  * Must be used together with `REDIS_TLS_CLIENT_CERT_FILE`
* `REDIS_TLS_VERIFY`: Certificate verification mode (optional)
  * Valid values: `"verify_peer"`, `"verify_none"`
  * Defaults: `"verify_peer"` when certificate files are provided, `"verify_none"` otherwise

#### SSL/TLS Configuration Examples

**Basic TLS without peer verification:**

```bash theme={null}
REDIS_URL=rediss://username:password@redis.example.com:6380
# or
REDIS_URL=redis://username:password@redis.example.com:6379
REDIS_SSL=true
```

**TLS with implicit CA certificate verification:**

```bash theme={null}
REDIS_URL=redis://username:password@redis.example.com:6379
REDIS_SSL=true
REDIS_TLS_VERIFY=verify_peer
```

**TLS with CA certificate validation:**

```bash theme={null}
REDIS_URL=rediss://username:password@redis.example.com:6380
REDIS_TLS_CA_CERT_FILE=/path/to/ca.crt
```

**Full mTLS authentication:**

```bash theme={null}
REDIS_URL=rediss://username:password@redis.example.com:6380
REDIS_TLS_CA_CERT_FILE=/path/to/ca.crt
REDIS_TLS_CLIENT_CERT_FILE=/path/to/client.crt
REDIS_TLS_CLIENT_KEY_FILE=/path/to/client.key
```

**mTLS with explicit verification mode:**

```bash theme={null}
REDIS_URL=rediss://username:password@redis.example.com:6380
REDIS_TLS_CA_CERT_FILE=/path/to/ca.crt
REDIS_TLS_CLIENT_CERT_FILE=/path/to/client.crt
REDIS_TLS_CLIENT_KEY_FILE=/path/to/client.key
REDIS_TLS_VERIFY=verify_peer # already defaults to verify_peer when certs are specified
```

### Security configuration

* `SECRET_KEY_BASE`: Base secret key for encryption
* `VAULT_KEY`: Vault encryption key

See [secret generation](#secret-generation) for how to generate these values.

### Feature configuration

* `FEATURE_ACCOUNT_SELF_SIGNUP`: Enable account self-signup (default: enabled)
  * If disabled, users must be invited to the Sequin instance by an admin. Turn this setting off if you'll be hosting Sequin at a public URL.
* `FEATURE_PROVISION_DEFAULT_USER`: Enable default user provisioning (default: enabled)
  * By default, Sequin provisions a default user on startup if one doesn't exist. This is a convenience feature to get started quickly. If you're hosting Sequin at a public URL, you should consider either changing the password for this user or disabling this feature.
* `SEQUIN_TELEMETRY_DISABLED`: Disable telemetry data collection (default: false)
  * Sequin collects telemetry data by default. While we're early, this **greatly** helps us improve the product. To opt-out, set this to `true`.
* `CRASH_REPORTING_DISABLED`: Disable crash reporting (default: false)
  * Sequin sends crash reports to Sentry by default. This is very useful for the Sequin team to proactively fix bugs. To opt-out, set this to `true`.

### Networking configuration

* `LONG_POLL_FALLBACK_MS`: Long poll fallback time in milliseconds (default: 3000)
  * This is the duration that Sequin will wait for a healthy websocket connection before falling back to HTTP long polling. If your network configuration disallows websocket connections, you should set this to a low value (e.g. 100ms).

### Email configuration

Email configuration is coming soon. [Please comment on this issue](https://github.com/sequinstream/sequin/issues/579) if you'd like to see this feature.

### OAuth configuration

To use GitHub OAuth as a sign-in/sign-up method, provide the following environment variables:

* `GITHUB_CLIENT_ID`: GitHub OAuth client ID
* `GITHUB_CLIENT_SECRET`: GitHub OAuth client secret
* `GITHUB_CLIENT_REDIRECT_URI`: GitHub OAuth callback URL, including the path `/auth/github/callback`
  * Example: `https://yourdomain.com/auth/github/callback`

### Metrics configuration

* `SEQUIN_METRICS_PORT`: Port number for the metrics endpoint (default: 8376)
  * This is the port that Sequin will expose Prometheus metrics on. Metrics are available at `/metrics` on this port.
* `SEQUIN_METRICS_USER`: Username required to access the metrics endpoint (optional)
* `SEQUIN_METRICS_PASSWORD`: Password required to access the metrics endpoint (optional)

  If **either** variable is set, Sequin secures the `/metrics` endpoint with HTTP Basic Authentication. With both unset, the endpoint is publicly accessible (recommended only for local development).

See [Metrics](/reference/metrics) reference for more information on the metrics exposed by Sequin.

## Replication slot flush intervals

Sequin's replication slot accumulates messages in memory before flushing them downstream. Flushing occurs whenever any of the three thresholds—maximum bytes, maximum messages, or maximum time—are reached. By default, the system uses settings that balance throughput and memory usage for most workloads. However, you can tune the following environment variables to experiment with flush intervals and batch sizes for your specific workload:

* `REPLICATION_FLUSH_MAX_ACCUMULATED_BYTES`: Maximum number of bytes to accumulate in memory before flushing the replication batch downstream. (Default: 100MB)
* `REPLICATION_FLUSH_MAX_ACCUMULATED_MESSAGES`: Maximum number of messages to accumulate before flushing. (Default: 100,000)
* `REPLICATION_FLUSH_MAX_ACCUMULATED_TIME_MS`: Maximum time (in milliseconds) to wait before flushing accumulated messages, even if neither of the above thresholds is reached. (Default: 50ms)

These settings allow you to control the batching behavior of Sequin's logical replication slot. The defaults are chosen to work well for most environments.

## Deploying to production

### Secret generation

For production environments, generate secure values for `SECRET_KEY_BASE` and `VAULT_KEY`:

```bash theme={null}
# Generate SECRET_KEY_BASE
openssl rand -base64 64

# Generate VAULT_KEY
openssl rand -base64 32
```

### Set `SERVER_CHECK_ORIGIN` and `SERVER_HOST`

If you're hosting Sequin at a public URL, you should set `SERVER_CHECK_ORIGIN` to `true` and `SERVER_HOST` to your public domain. See [General configuration](#general-configuration).

### Active-passive architecture

You can run multiple Sequin nodes at the same time safely. They will run in an active-passive configuration. This is helpful for both rolling deploys and high availability.

In this setup:

* One node operates as the active node, running all sinks
* Additional nodes operate as passive ("hot standby") nodes
* All nodes can serve web traffic and API requests
* If the active node fails, a passive node automatically promotes to active

Requirements for multi-node deployment:

* All nodes must share:
  * The same Postgres database
  * The same Redis instance
  * Identical configuration

Sequin uses Redis for distributed locking and leader election.

### Runtime requirements

#### Redis

Sequin requires Redis to be persistent and durable between restarts (i.e. Redis won't be wiped when you restart Sequin).

Any key-value store that works with the Redis protocol (e.g. [KeyDB](https://keydb.dev/)) will work with Sequin.