# Configuration Options

All configuration options can be set via command line flags, environment variables or config file.

All options are optional.

Environment variables must be prefixed with SHAPER_ and use uppercase letters and underscores.
For example, `--nats-token 123` turns into `SHAPER_NATS_TOKEN=123`.

The config file format is plain text, with one flag per line. The flag name and value are separated by whitespace.
For example, `--nats-token 123` turns into `nats-token 123`.

To use a config file, pass the `--config-file` flag with the path to the config file.

You can combine all three methods to set configuration options.
Command-line args have the highest priority.
Environment variables have the next-highest priority.
The config file has the lowest priority.

All options are listed below roughly in order of how likely you want to change them.

## `addr`

Web server address to listen on

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--addr` | `SHAPER_ADDR` | `localhost:5454` |

## `dir`

Directory to store data in

| Flag | Env Var | Default | Docker Default |
| ---- | ------- | ------- | ------- |
| `-d`, `--dir` | `SHAPER_DIR` | `/home/<user>/.shaper` | `/data` |

## `css`

CSS string to inject into the frontend.

Also see [Custom Styles](https://taleshape.com/shaper/docs/custom-styles).

| Flag | Env Var |
| ---- | ------- |
| `--css` | `SHAPER_CSS` |

## `favicon`

Path to a favicon file to override favicon. Must end with `.svg` or `.ico`.

| Flag | Env Var |
| ---- | ------- |
| `--favicon` | `SHAPER_FAVICON` |

## `init-sql`

SQL string to execute on startup.

Supports environment variables in the format `$VAR` or `${VAR}`.

| Flag | Env Var |
| ---- | ------- |
| `--init-sql` | `SHAPER_INIT_SQL` |

## `init-sql-file`

Read SQL from a file to execute on startup.

In most cases you probably want to use `init-sql-file` over `init-sql` since it makes managing longer SQL scripts easier.

Note that Shaper doesn't error if the file doesn't exist.

| Flag | Env Var | Default | Docker Default |
| ---- | ------- | ------- | --------------- |
| `--init-sql-file` | `SHAPER_INIT_SQL_FILE` | `[--dir]/init.sql` | `/var/lib/shaper/init.sql` |

## `log-level`

Log level to use. One of `debug`, `info`, `warn`, `error`.

If logs get too verbose in production, set to `warn`.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--log-level` | `SHAPER_LOG_LEVEL` | `info` |

## `snapshot-s3-bucket`

S3 bucket for snapshots (required for snapshots).

| Flag | Env Var |
| ---- | ------- |
| `--snapshot-s3-bucket` | `SHAPER_SNAPSHOT_S3_BUCKET` |

## `snapshot-s3-endpoint`

S3 endpoint URL (optional).
Must be set if you are using a non-AWS S3-compatible storage service.
Defaults to AWS S3 endpoint if not set.
AWS S3 endpoint depends on the set [region](#snapshot-s3-region) if the endpoint is not set explicitly.

| Flag | Env Var |
| ---- | ------- |
| `--snapshot-s3-endpoint` | `SHAPER_SNAPSHOT_S3_ENDPOINT` |

## `snapshot-s3-access-key`

S3 access key (optional).
If the access key and secret key are not set, we use a credential chain to lookup credentials from environment variables, shared credentials file, or IAM role.
This means you can set the access key as `AWS_ACCESS_KEY_ID` environment variable instead.

| Flag | Env Var |
| ---- | ------- |
| `--snapshot-s3-access-key` | `SHAPER_SNAPSHOT_S3_ACCESS_KEY` |

## `snapshot-s3-secret-key`

S3 secret key (optional).
If the access key and secret key are not set, we use a credential chain to lookup credentials from environment variables, shared credentials file, or IAM role.
This means you can set the secret key as `AWS_SECRET_ACCESS_KEY` environment variable instead.

| Flag | Env Var |
| ---- | ------- |
| `--snapshot-s3-secret-key` | `SHAPER_SNAPSHOT_S3_SECRET_KEY` |

## `snapshot-s3-region`

AWS region for S3 (optional).
If not set, tries to lookup region from `AWS_REGION` and `AWS_DEFAULT_REGION` environment variables.
If none are set, defaults to `us-east-1`.

| Flag | Env Var |
| ---- | ------- |
| `--snapshot-s3-region` | `SHAPER_SNAPSHOT_S3_REGION` |

## `snapshot-time`

Time to run daily snapshots, format: HH:MM.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--snapshot-time` | `SHAPER_SNAPSHOT_TIME` | `01:00` |

## `no-snapshots`

Disable automatic snapshots. Set this when you want to configure S3 for automatic snapshot restores but don't want to create snapshots automatically.

| Flag | Env Var |
| ---- | ------- |
| `--no-snapshots` | `SHAPER_NO_SNAPSHOTS=true` |

## `no-auto-restore`

Disable automatic restore of latest snapshot on startup. Set this when you want to create snapshots but don't want to restore automatically on startup.

| Flag | Env Var |
| ---- | ------- |
| `--no-auto-restore` | `SHAPER_NO_AUTO_RESTORE=true` |

## `no-public-sharing`

Disable public sharing of dashboards.

Also, previously shared dashboards will not be accessible while this flag is set.

| Flag | Env Var |
| ---- | ------- |
| `--no-public-sharing` | `SHAPER_NO_PUBLIC_SHARING=true` |

## `no-password-protected-sharing`

Disable password-protected sharing of dashboards.

This will also disable existing password-protected shares. But it will not delete them. So if you later remove the flag, the password-protected shares will be available again.

| Flag | Env Var |
| ---- | ------- |
| `--no-password-protected-sharing` | `SHAPER_NO_PASSWORD_PROTECTED_SHARING=true` |

## `no-tasks`

Disable tasks functionality.

This will also disable existing tasks. But it will not delete them. So if you later remove the flag, the tasks will be available again.

| Flag | Env Var |
| ---- | ------- |
| `--no-tasks` | `SHAPER_NO_TASKS=true` |

## `no-edit`

Disable editing dashboards via UI.

This is useful if you want to ensure all edits are done via the [file-based workflow](https://taleshape.com/shaper/docs/git-workflow).
Note that this doesn't disable tasks. That's because currently tasks cannot be managed as files. This will change in the future.

| Flag | Env Var |
| ---- | ------- |
| `--no-edit` | `SHAPER_NO_EDIT=true` |

## `tls-domain`

Domain name to use for TLS certificates.
Setting this will enable TLS and listen on `https-host`:443 for HTTPS requests and on `https-host`:80 for HTTP requests to redirect to HTTPS.
Certificates are automatically generated using [Let's Encrypt](https://letsencrypt.org/).
When setting `tls-domain` you must not set `addr` or `basepath`.

| Flag | Env Var |
| ---- | ------- |
| `--tls-domain` | `SHAPER_TLS_DOMAIN` |

## `tls-email`

Email address to use for TLS certificates, optional.
Lets Encrypt uses this email address to send notifications about certificate expiration and other issues.

| Flag | Env Var |
| ---- | ------- |
| `--tls-email` | `SHAPER_TLS_EMAIL` |

## `tls-cache`

Directory to store TLS certificates and cache in.
This is used to cache the TLS certificates and avoid rate limits from Let's Encrypt.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--tls-cache` | `SHAPER_TLS_CACHE` | `[--dir]/letsencrypt-cache` |

## `https-host`

Hostname to listen on for HTTPS requests.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--https-host` | `SHAPER_HTTPS_HOST` | `""` |

## `basepath`

Base URL path the frontend is served from.

Override if you are using a reverse proxy and serve the frontend from a subpath.

Can be a path starting with a slash or a full URL.
If you want to use the [Download API](https://taleshape.com/shaper/docs/api-endpoints) with `mode=url`, you also have to set basepath to a full URL, otherwise URLs will be relative only.
Does not apply if [tls-domain](#tls-domain) is set.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--basepath` | `SHAPER_BASEPATH` | `/` |

## `nats-host`

NATS server hostname to listen on.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--nats-host` | `SHAPER_NATS_HOST` | `0.0.0.0` |

## `nats-port`

NATS server port to listen on.

Set to `0` to disable listening on any port.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `-p`, `--nats-port` | `SHAPER_NATS_PORT` | `0` |

## `nats-token`

Admin authentication token for the NATS server.

Set to manage NATS via the NATS CLI or other tools.

To get access to ingest data, use an API key instead.

By default, no authentication is used. That means once you set a NATS port you should also set a token to secure the NATS server.

| Flag | Env Var |
| ---- | ------- |
| `-t`, `--nats-token` | `SHAPER_NATS_TOKEN` |

## `nats-servers`

Use an external NATS server.

Specify one or more addresses as a comma-separated list.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--nats-servers` | `SHAPER_NATS_SERVERS` | Using internal NATS server |

## `nats-max-store`

Maximum storage in bytes for JetStream.

Set to `0` for unlimited storage.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--nats-max-store` | `SHAPER_NATS_MAX_STORE` | `0` |

## `nats-js-key`

JetStream encryption key. Set to encrypt JetStream data on disk.

Watch out: You cannot change or remove the key once set. Then NATS will fail to load existing data.

| Flag | Env Var |
| ---- | ------- |
| `--nats-js-key` | `SHAPER_NATS_JS_KEY` |

## `nats-dir`

Override JetStream storage directory.

Defaults to `[--dir]/nats`. This means that if you set `--dir /data`, then the NATS storage directory will be `/data/nats`.

| Flag | Env Var |
| ---- | ------- |
| `--nats-dir` | `SHAPER_NATS_DIR` |

## `sqlite`

Override sqlite DB file that is used for system state.

Use this to change the location of the SQLite database file.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--sqlite` | `SHAPER_SQLITE` | `[--dir]/shaper_internal.sqlite` |

## `duckdb`

Override DuckDB DSN.

Use this to change the location of the DuckDB database file.

**Shaper has explicit support for using an in-memory database by setting this option to `:memory:`:**

In memory-mode Shaper will create a new database for every dashboard and task.
Plus, using `ATTACH` in dashboards is supported in memory-mode.

_Note that memory-mode sometimes temporarily write data to disk when working with datasets bigger than memory_

You can pass additional parameters to DuckDB by adding them to the DSN.
For example: `--duckdb ./.data/shaper.duckdb?allow_unsigned_extensions=true`

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--duckdb` | `SHAPER_DUCKDB` | `[--dir]/shaper.duckdb` |

## `duckdb-ext-dir`

Override DuckDB extension directory.

By default it uses the system's default DuckDB extension directory, which is `~/.duckdb/extensions/` on most systems.
In Docker it defaults to `/data/duckdb_extensions` so it's easy to mount extensions and not have to download them every time the container restarts.

| Flag | Env Var | Default | Docker Default |
| ---- | ------- | ------- | --------------- |
| `--duckdb-ext-dir` | `SHAPER_DUCKDB_EXT_DIR` | `~/.duckdb/extensions/` | `/data/duckdb_extensions` |

## `duckdb-secret-dir`

Override DuckDB secret directory.

This is where DuckDB stores persistent secrets (without encryption).

| Flag | Env Var | Default | Docker Default |
| ---- | ------- | ------- | --------------- |
| `--duckdb-secret-dir` | `SHAPER_DUCKDB_SECRET_DIR` | `~/.duckdb/stored_secrets` | `/root/.duckdb/stored_secrets` |

## `jwtexp`

JWT expiration duration. Used for authentication tokens.

Pass a duration string like `15m` for 15 minutes, `1h:15m` for 1 hour 15 minutes, etc.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--jwtexp` | `SHAPER_JWTEXP` | `15m0s` |

## `sessionexp`

Session expiration duration. Used for user sessions.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--sessionexp` | `SHAPER_SESSIONEXP` | `720h0m0s` |

## `inviteexp`

Invite expiration duration. Used for user invites.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--inviteexp` | `SHAPER_INVITEEXP` | `168h0m0s` |

## `no-chrome-sandbox`

Disables the sandboxing of the headless chrome.
We automatically set this in docker since we don't have the permissions to do that in the container and the container already is the sandbox.

| Flag | Env Var | Default | Docker Default |
| ---- | ------- | ------- | ------- |
| `--no-chrome-sandbox` | `SHAPER_NO_CHROME_SANDBOX` | `false` | `true` |

## `stream-prefix`

Prefix for NATS stream and KV bucket names.
Will be prepended to `ingest-stream`, `state-stream`, `config-kv-bucket`, and `tmp-dashboards-kv-bucket`.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--stream-prefix` | `SHAPER_STREAM_PREFIX` | `""` |

## `node-id-file`

File to store and lookup the node ID.

Binding node IDs to the local file system means they reset when the file system is reset.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--node-id-file` | `SHAPER_NODE_ID_FILE` | `[--dir]/node-id.txt` |

## `ingest-stream`

Override NATS stream name for ingest messages.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--ingest-stream` | `SHAPER_INGEST_STREAM` | `shaper-ingest` |

## `state-stream`

Override NATS stream name for Shaper-internal state messages.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--state-stream` | `SHAPER_STATE_STREAM` | `shaper-state` |

## `config-kv-bucket`

Override NATS config KV bucket name.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--config-kv-bucket` | `SHAPER_CONFIG_KV_BUCKET` | `shaper-config` |

## `tmp-dashboards-kv-bucket`

Override name for NATS KV bucket to store temporary dashboards.
Temporary dashboards are created to view unsaved versions when editing dashboards.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--tmp-dashboards-kv-bucket` | `SHAPER_TMP_DASHBOARDS_KV_BUCKET` | `shaper-tmp-dashboards` |

## `tmp-dashboards-ttl`

Override time-to-live for temporary dashboards.
Temporary dashboards are created to view unsaved versions when editing dashboards.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--tmp-dashboards-ttl` | `SHAPER_TMP_DASHBOARDS_TTL` | `24h` |

## `downloads-kv-bucket`

Override name for NATS KV bucket to store download intents.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--downloads-kv-bucket` | `SHAPER_DOWNLOADS_KV_BUCKET` | `shaper-downloads` |

## `downloads-ttl`

Override time-to-live for download intents. The shorter the safer.

Make sure this is always shorter than [tmp-dashboards-ttl](#tmp-dashboards-ttl) since downloads can be used to download temporary dashboards.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--downloads-ttl` | `SHAPER_DOWNLOADS_TTL` | `10m` |

## `task-stream`

Override NATS stream name for task work queue.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-stream` | `SHAPER_TASK_STREAM` | `shaper-tasks` |

## `task-results-stream`

Override NATS stream name for task results.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-results-stream` | `SHAPER_TASK_RESULTS_STREAM` | `shaper-task-results` |

## `ingest-max-age`

Maximum age of messages in the ingest stream.

Set to `0s` for indefinite retention.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--ingest-max-age` | `SHAPER_INGEST_MAX_AGE` | `0s` |

## `state-max-age`

Maximum age of messages in the state stream.

Set to `0s` for indefinite retention.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--state-max-age` | `SHAPER_STATE_MAX_AGE` | `0s` |

## `task-results-max-age`

Maximum age of messages in the task results stream.

Set to `0s` for indefinite retention.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-results-max-age` | `SHAPER_TASK_RESULTS_MAX_AGE` | `0s` |

## `ingest-consumer-name-file`

File to store and lookup name for the ingest consumer.

Binding consumer names to the local file system means they reset when the file system is reset.
This works well together with Docker containers.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--ingest-consumer-name-file` | `SHAPER_INGEST_CONSUMER_NAME_FILE` | `[--dir]/ingest-consumer-name.txt` |

## `task-queue-consumer-name`

Name of the consumer for the task stream.
Note that we are not using a file here since the name is shared between all nodes in a cluster since we only have a single consumer and the stream is a work queue.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-queue-consumer-name` | `SHAPER_TASK_QUEUE_CONSUMER_NAME` | `shaper-task-queue-consumer` |

## `snapshot-stream`

NATS stream name internally used to coordinate scheduled snapshots.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--snapshot-stream` | `SHAPER_SNAPSHOT_STREAM` | `shaper-snapshots` |

## `snapshot-consumer-name`

NATS consumer name internally used to coordinate scheduled snapshots.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--snapshot-consumer-name` | `SHAPER_SNAPSHOT_CONSUMER_NAME` | `shaper-snapshot-consumer` |

## `subject-prefix`

Prefix for NATS subjects.

Is prepended to `ingest-subject-prefix` and `state-subject-prefix`.

Must be a valid NATS subject name. Should probably end with a dot.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--subject-prefix` | `SHAPER_SUBJECT_PREFIX` | `""` |

## `ingest-subject-prefix`

Prefix for ingest NATS subjects.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--ingest-subject-prefix` | `SHAPER_INGEST_SUBJECT_PREFIX` | `shaper.ingest.` |

## `state-subject-prefix`

Prefix for state NATS subjects.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--state-subject-prefix` | `SHAPER_STATE_SUBJECT_PREFIX` | `shaper.state.` |

## `tasks-subject-prefix`

Prefix for tasks NATS subjects.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-subject-prefix` | `SHAPER_TASK_SUBJECT_PREFIX` | `shaper.tasks.` |

## `task-results-subject-prefix`

Prefix for task results NATS subjects.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-results-subject-prefix` | `SHAPER_TASK_RESULTS_SUBJECT_PREFIX` | `shaper.task-results.` |

## `task-broadcast-subject`

NATS subject for tasks to run on all nodes in a cluster when running manual tasks.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--task-broadcast-subject` | `SHAPER_TASK_BROADCAST_SUBJECT` | `shaper.task-broadcast` |

## `snapshot-subject-prefix`

Prefix for snapshots NATS subjects.

| Flag | Env Var | Default |
| ---- | ------- | ------- |
| `--snapshot-subject-prefix` | `SHAPER_SNAPSHOT_SUBJECT_PREFIX` | `shaper.snapshots.` |