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.
Web server address to listen on
Flag | Env Var | Default |
---|---|---|
--addr | SHAPER_ADDR | localhost:5454 |
Directory to store data in
Flag | Env Var | Default | Docker Default |
---|---|---|---|
-d , --dir | SHAPER_DIR | /home/jorin/.shaper | /data |
CSS string to inject into the frontend.
Also see Custom Styles
Flag | Env Var |
---|---|
--css | SHAPER_CSS |
favicon
Section titled “favicon”Path to a favicon file to override favicon. Must end with .svg
or .ico
.
Flag | Env Var |
---|---|
--favicon | SHAPER_FAVICON |
init-sql
Section titled “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
Section titled “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 |
no-public-sharing
Section titled “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 |
basepath
Section titled “basepath”Base URL path the frontend is served from.
Override if you are using a reverse proxy and serve the frontend from a subpath.
Flag | Env Var | Default |
---|---|---|
--basepath | SHAPER_BASEPATH | / |
nats-host
Section titled “nats-host”NATS server hostname to listen on.
Flag | Env Var | Default |
---|---|---|
--nats-host | SHAPER_NATS_HOST | 0.0.0.0 |
nats-port
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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 |
duckdb
Section titled “duckdb”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.
Flag | Env Var | Default |
---|---|---|
--duckdb | SHAPER_DUCKDB | [--dir]/shaper.duckdb |
duckdb-ext-dir
Section titled “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 |
schema
Section titled “schema”Database schema name for internal tables
Flag | Env Var | Default |
---|---|---|
--schema | SHAPER_SCHEMA | _shaper |
jwtexp
Section titled “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
Section titled “sessionexp”Session expiration duration. Used for user sessions.
Flag | Env Var | Default |
---|---|---|
--sessionexp | SHAPER_SESSIONEXP | 720h0m0s |
inviteexp
Section titled “inviteexp”Invite expiration duration. Used for user invites.
Flag | Env Var | Default |
---|---|---|
--inviteexp | SHAPER_INVITEEXP | 168h0m0s |
stream-prefix
Section titled “stream-prefix”Prefix for NATS stream and KV bucket names.
Will be prepened to ingest-stream
, state-stream
, and config-kv-bucket
.
Flag | Env Var | Default |
---|---|---|
--stream-prefix | SHAPER_STREAM_PREFIX | "" |
ingest-stream
Section titled “ingest-stream”Override NATS stream name for ingest messages.
Flag | Env Var | Default |
---|---|---|
--ingest-stream | SHAPER_INGEST_STREAM | shaper-ingest |
state-stream
Section titled “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
Section titled “config-kv-bucket”Override NATS config KV bucket name.
Flag | Env Var | Default |
---|---|---|
--config-kv-bucket | SHAPER_CONFIG_KV_BUCKET | shaper-config |
ingest-max-age
Section titled “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
Section titled “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 |
ingest-consumer-name-file
Section titled “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 |
state-consumer-name-file
Section titled “state-consumer-name-file”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.
Flag | Env Var | Default |
---|---|---|
--state-consumer-name-file | SHAPER_STATE_CONSUMER_NAME_FILE | [--dir]/state-consumer-name.txt |
subject-prefix
Section titled “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
Section titled “ingest-subject-prefix”Prefix for ingest NATS subjects.
Flag | Env Var | Default |
---|---|---|
--ingest-subject-prefix | SHAPER_INGEST_SUBJECT_PREFIX | shaper.ingest. |
state-subject-prefix
Section titled “state-subject-prefix”Prefix for state NATS subjects.
Flag | Env Var | Default |
---|---|---|
--state-subject-prefix | SHAPER_STATE_SUBJECT_PREFIX | shaper.state. |