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.

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