Skip to content

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.

Web server address to listen on

FlagEnv VarDefault
--addrSHAPER_ADDRlocalhost:5454

Directory to store data in

FlagEnv VarDefaultDocker Default
-d, --dirSHAPER_DIR/home/jorin/.shaper/data

CSS string to inject into the frontend.

Also see Custom Styles

FlagEnv Var
--cssSHAPER_CSS

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

FlagEnv Var
--faviconSHAPER_FAVICON

SQL string to execute on startup.

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

FlagEnv Var
--init-sqlSHAPER_INIT_SQL

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.

FlagEnv VarDefaultDocker Default
--init-sql-fileSHAPER_INIT_SQL_FILE[--dir]/init.sql/var/lib/shaper/init.sql

Disable public sharing of dashboards.

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

FlagEnv Var
--no-public-sharingSHAPER_NO_PUBLIC_SHARING=true

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.

FlagEnv Var
--no-tasksSHAPER_NO_TASKS=true

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.

FlagEnv Var
--tls-domainSHAPER_TLS_DOMAIN

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

FlagEnv Var
--tls-emailSHAPER_TLS_EMAIL

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

FlagEnv VarDefault
--tls-cacheSHAPER_TLS_CACHE[--dir]/letsencrypt-cache

Hostname to listen on for HTTPS requests.

FlagEnv VarDefault
--https-hostSHAPER_HTTPS_HOST""

Base URL path the frontend is served from.

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

FlagEnv VarDefault
--basepathSHAPER_BASEPATH/

NATS server hostname to listen on.

FlagEnv VarDefault
--nats-hostSHAPER_NATS_HOST0.0.0.0

NATS server port to listen on.

Set to 0 to disable listening on any port.

FlagEnv VarDefault
-p, --nats-portSHAPER_NATS_PORT0

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.

FlagEnv Var
-t, --nats-tokenSHAPER_NATS_TOKEN

Use an external NATS server.

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

FlagEnv VarDefault
--nats-serversSHAPER_NATS_SERVERSUsing internal NATS server

Maximum storage in bytes for JetStream.

Set to 0 for unlimited storage.

FlagEnv VarDefault
--nats-max-storeSHAPER_NATS_MAX_STORE0

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.

FlagEnv Var
--nats-js-keySHAPER_NATS_JS_KEY

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.

FlagEnv Var
--nats-dirSHAPER_NATS_DIR

Override DuckDB DSN.

Use this to change the location of the DuckDB database file. Or get creative and us a DSN DuckDB supports that is not even on the local file system.

FlagEnv VarDefault
--duckdbSHAPER_DUCKDB[--dir]/shaper.duckdb

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.

FlagEnv VarDefaultDocker Default
--duckdb-ext-dirSHAPER_DUCKDB_EXT_DIR~/.duckdb/extensions//data/duckdb_extensions

Database schema name for internal tables

FlagEnv VarDefault
--schemaSHAPER_SCHEMA_shaper

JWT expiration duration. Used for authentication tokens.

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

FlagEnv VarDefault
--jwtexpSHAPER_JWTEXP15m0s

Session expiration duration. Used for user sessions.

FlagEnv VarDefault
--sessionexpSHAPER_SESSIONEXP720h0m0s

Invite expiration duration. Used for user invites.

FlagEnv VarDefault
--inviteexpSHAPER_INVITEEXP168h0m0s

Prefix for NATS stream and KV bucket names. Will be prepened to ingest-stream, state-stream, and config-kv-bucket.

FlagEnv VarDefault
--stream-prefixSHAPER_STREAM_PREFIX""

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.

FlagEnv VarDefault
--node-id-fileSHAPER_NODE_ID_FILE[--dir]/node-id.txt

Override NATS stream name for ingest messages.

FlagEnv VarDefault
--ingest-streamSHAPER_INGEST_STREAMshaper-ingest

Override NATS stream name for Shaper-internal state messages.

FlagEnv VarDefault
--state-streamSHAPER_STATE_STREAMshaper-state

Override NATS config KV bucket name.

FlagEnv VarDefault
--config-kv-bucketSHAPER_CONFIG_KV_BUCKETshaper-config

Override NATS stream name for task work queue.

FlagEnv VarDefault
--task-streamSHAPER_TASK_STREAMshaper-tasks

Override NATS stream name for task results.

FlagEnv VarDefault
--task-results-streamSHAPER_TASK_RESULTS_STREAMshaper-task-results

Maximum age of messages in the ingest stream.

Set to 0s for indefinite retention.

FlagEnv VarDefault
--ingest-max-ageSHAPER_INGEST_MAX_AGE0s

Maximum age of messages in the state stream.

Set to 0s for indefinite retention.

FlagEnv VarDefault
--state-max-ageSHAPER_STATE_MAX_AGE0s

Maximum age of messages in the task results stream.

Set to 0s for indefinite retention.

FlagEnv VarDefault
--task-results-max-ageSHAPER_TASK_RESULTS_MAX_AGE0s

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.

FlagEnv VarDefault
--ingest-consumer-name-fileSHAPER_INGEST_CONSUMER_NAME_FILE[--dir]/ingest-consumer-name.txt

File to store and lookup name for the state 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.

FlagEnv VarDefault
--state-consumer-name-fileSHAPER_STATE_CONSUMER_NAME_FILE[--dir]/state-consumer-name.txt

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.

FlagEnv VarDefault
--task-consumer-nameSHAPER_TASK_CONSUMER_NAMEshaper-task-queue-consumer

File to store and lookup name for the task results 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.

FlagEnv VarDefault
--task-results-consumer-name-fileSHAPER_TASK_RESULTS_CONSUMER_NAME_FILE[--dir]/task-results-consumer-name.txt

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.

FlagEnv VarDefault
--subject-prefixSHAPER_SUBJECT_PREFIX""

Prefix for ingest NATS subjects.

FlagEnv VarDefault
--ingest-subject-prefixSHAPER_INGEST_SUBJECT_PREFIXshaper.ingest.

Prefix for state NATS subjects.

FlagEnv VarDefault
--state-subject-prefixSHAPER_STATE_SUBJECT_PREFIXshaper.state.

Prefix for tasks NATS subjects.

FlagEnv VarDefault
--task-subject-prefixSHAPER_TASK_SUBJECT_PREFIXshaper.tasks.

Prefix for task results NATS subjects.

FlagEnv VarDefault
--task-results-subject-prefixSHAPER_TASK_RESULTS_SUBJECT_PREFIXshaper.task-results.

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

FlagEnv VarDefault
--task-broadcast-subjectSHAPER_TASK_BROADCAST_SUBJECTshaper.task-broadcast