Configuration via Environment Variables

"Configuration" throughout the documentation and codebase refers to these variables which are statically set when the process launches. Changing them requires a restart, however they don't need to be changed much once set.

The term "Settings" is distinct from these and refers to runtime-configurable values which are stored in the database and not via environment variables. These can be changed at any time via the API or the Admin settings page.

General

These settings general infrastructure-level configuration settings for managing a Storyden deployment.

LOG_LEVEL

type	debug, info, warn, error
default	info

Can be set to either:

• debug
• info
• warn
• error

LOG_FORMAT

type	string
default	none

Can be set to either:

• (not set) (default) somewhat human readable "logfmt" format logs for simple setups
• dev for developer-friendly logs, with colours and attributes on separate lines for readability
• json for machine-readable logs, mainly for log aggregators, etc.

RUN_FRONTEND

type	string
default	(empty string)

Determines whether or not the backend service will also start the frontend Node.js process. When empty, it will not

When a path is provided, Storyden will execute node <path> to start the frontend process. This is used by the fullstack Docker image to start the frontend process in the same container as the backend.

PROXY_FRONTEND_ADDRESS

type	url (e.g. http://example.com)
default	(empty string)

Used in conjunction with RUN_FRONTEND. This is the address that the frontend will be available at. This is used by the fullstack Docker image to proxy requests that don't match any /api or other routes to the frontend process.

In the default fullstack image, this is set to http://localhost:3000 which is the default port for the Next.js process.

Development tools

Configuration settings for aiding in development of Storyden clients.

DEV_CHAOS_SLOW_MODE

type	duration (e.g. 1h, 1m, 1s)
default	none

Simulates slow requests.

This will add a random delay between zero and this value to all requests. This is useful for testing how the client handles slow responses.

DEV_CHAOS_FAIL_RATE

type	float (e.g. 1.0, 1.5)
default	none

A value between 0 and 1 which simulates failed requests.

This will add a random failure to all requests. This is useful for testing how the client handles "internal server error" responses.

Core configuration

Configuration settings for core functionality, pretty much all of these will need to be configured for production installations, excepting perhaps LISTEN_ADDR.

DATABASE_URL

type	string
default	sqlite://data/data.db?_pragma=foreign_keys(1)

The database URL to connect to. This can be a SQLite, PostgreSQL, or CockroachDB URL.

The accepted schemes for this URL are:

• sqlite:// or sqlite3:// for SQLite or Litestream.
• postgres:// or postgresql:// for PostgreSQL, CockroachDB and any other PostgreSQL-compatible database

LISTEN_ADDR

type	string
default	0.0.0.0:8000

The interface on which the API service will for HTTP requests.

Typically, in a containerised environment, this should be all interfaces (0.0.0.0.)

PUBLIC_WEB_ADDRESS

type	url (e.g. http://example.com)
default	http://localhost:3000

The address at which the web frontend will be hosted.

This must be set to the public URL that users of the instance will access the frontend client. It is used to determine things such as cookie domain attributes, CORS policy, WebAuthn attributes and other necessary settings. The scheme may be used by some internal components to determine whether the instance is running in a secure context or not.

This is by default http://localhost:3000 when running locally, or when deploying to production, https://<your-domain>.

PUBLIC_API_ADDRESS

type	url (e.g. http://example.com)
default	http://localhost:8000

The address at which the public API will be accessible.

This is also used for things such as cookies, CORS, etc.

Please note that both the public API address and public web address must share the same root domain name as Storyden cookies are configured to be issued under this assumption. It also makes a lot of cross-origin and cookie configurations easier to make secure.

Rate limiting

You can (and should) set rate limiting parameters for any production deployment. Storyden uses a sliding-window-incrementing-counters algorithm to track usage by members and bots which is friendly to bursts of activity while still preventing persistent abuse patterns.

The default values should be sufficient for a small to medium-sized deployment, but you may want to increase them for larger deployments while maintaining adequate hardware and database resources.

Currently, rate limits are applied based on the client's IP address (taking into account various proxy-forwarded headers.)

The rate limiter will store its state in-memory unless a CACHE_PROVIDER is configured. In that case, the rate limiter will store its state in the cache provider.

RATE_LIMIT

type	integer (number without decimal point)
default	1000

The amount of requests that a user can make within the RATE_LIMIT_PERIOD.

RATE_LIMIT_PERIOD

type	duration (e.g. 1h, 1m, 1s)
default	1h

The period of time in which the RATE_LIMIT is applied.

This is a sliding window, so the RATE_LIMIT is applied to the last RATE_LIMIT_PERIOD of requests.

RATE_LIMIT_EXPIRE

type	duration (e.g. 1h, 1m, 1s)
default	1m

The expiry time of the rate limit counters.

Telemetry and monitoring

Configuration for monitoring via OpenTelemetry-compatible software.

OTEL_PROVIDER

type	string
default	(empty string)

Either:

• otlp for any standard OpenTelemetry collector.
• sentry for Sentry (which is OpenTelemetry-compatible, however requires its own specific configuration.)
• logger for local logging to the console. This is only really useful for Storyden developers and is very noisy.

OTEL_EXPORTER_OTLP_ENDPOINT

type	url (e.g. http://example.com)
default	(empty string)

The collector endpoint for sending OTEL data.

SENTRY_DSN

type	string
default	(empty string)

When OTEL_PROVIDER is set to sentry, this is the DSN for the Sentry project.

Email

Email sending configuration. This must be enabled in order to enable email-based authentication and password reset functionality.

EMAIL_PROVIDER

type	string
default	none

Either:

• unset (default) for no email sending. Email sending is not a requirement for a production deployment.
• sendgrid for SendGrid based email sending.
• mock for logging emails to the console. Only useful for Storyden developers and testing.

SENDGRID_FROM_NAME

type	string
default	none

The name that will be used as the sender name for emails sent via SendGrid.

This is typically the name of your community or organisation.

SENDGRID_FROM_ADDRESS

type	string
default	none

The email address that will be used as the sender address for emails sent via SendGrid.

This is typically a no-reply address, such as no-reply@<your-domain>.

SENDGRID_API_KEY

type	string
default	none

The API key for the SendGrid account. This is required for sending emails via SendGrid.

This is typically a long string of characters that you can generate in the SendGrid dashboard.

SMS

SMS sending configuration. This must be enabled in order to support SMS-based authentication.

SMS_PROVIDER

type	string
default	none

Either:

• unset (default) for no SMS sending. SMS sending is not a requirement for a production deployment.
• twilio for Twilio based SMS sending.
• mock for logging SMS to the console. Only useful for Storyden developers and testing.

TWILIO_ACCOUNT_SID

type	string
default	none

The account SID for the Twilio account.

This is typically a long string of characters that you can view in the Twilio dashboard.

TWILIO_PHONE_NUMBER

type	string
default	none

The phone number that will be used as the sender number for SMS sent via Twilio.

TWILIO_AUTH_TOKEN

type	string
default	none

The auth token for the Twilio account. This is required for sending SMS via Twilio.

This is typically a long string of characters that you can generate in the Twilio dashboard.

Assets/file storage

Configuration for storing files such as avatars, uploaded images, etc.

ASSET_STORAGE_TYPE

type	string
default	none

Either:

• local for local file storage.
• s3 for any Amazon S3-compatible storage, such as S3 itself (obviously...), Google Cloud Storage, Cloudflare R2, Minio, etc.

ASSET_STORAGE_LOCAL_PATH

type	string
default	none

When ASSET_STORAGE_TYPE is set to local, this is the path to the directory where files will be stored.

S3_SECURE

type	boolean (true or false, case sensitive)
default	true

When ASSET_STORAGE_TYPE is set to s3, this determines whether or not to use HTTPS for the S3 connection. You should always set this to true unless your S3-compatible storage provider is internally but not publicly accessible, such as in a Kubernetes cluster or running on the same host.

S3_ENDPOINT

type	string
default	none

The endpoint for the S3-compatible storage provider. This is typically the base URL of the provider, such as https://s3.amazonaws.com for AWS S3, or https://storage.googleapis.com for Google Cloud Storage, etc.

S3_BUCKET

type	string
default	none

The bucket name for Storyden assets to be stored in.

S3_REGION

type	string
default	none

Most S3-compatible storage providers require a region to be specified. This is typically the region in which the bucket is located, such as us-east-1 for AWS S3.

However, some providers do not use regions but S3-compatible clients still require this to be set. In most cases, the provider will give you a value for this, such as auto when using Cloudflare R2.

S3_ACCESS_KEY

type	string
default	none

The access key for the S3-compatible storage provider.

S3_SECRET_KEY

type	string
default	none

The secret key for the S3-compatible storage provider.

Cache

Configuration for cachine. Caching is optional in Storyden, but is recommended for larger deployments to reduce process memory usage.

CACHE_PROVIDER

type	string
default	(empty string)

When empty, caching will use an efficient in-memory store. This is usually fine for small to medium-sized deployments however it's worth keeping an eye on your deployment's machine memory usage.

When set to redis, Storyden will use Redis as a cache provider. This is recommended for larger deployments that receive a lot of traffic. The cache provider is also used for the rate limiter so that it can be shared across multiple instances of Storyden.

This is necessary for deploying replica instances of Storyden that are backed by the same persistence layers (database, asset storage, etc.)

REDIS_URL

type	url (e.g. http://example.com)
default	(empty string)

The Redis URL to connect to.

This is a full URL with redis:// as the scheme. You can set the username and password using the URL format, for example: redis://<username>:<password>@<host>:<port>.

Message queue

Configuration for message/job queue. This is not required for Storyden to run, but it can improve performance, reliability and reduce memory usage in larger deployments.

QUEUE_TYPE

type	string
default	internal

Either:

• Default (no value): in-memory Go channels. This is fast and efficient, but not persistent across restarts and will add a bit of memory usage to the process.
• amqp: RabbitMQ. This is a persistent message queue that is fast and reliable. It is recommended for larger deployments and is necessary for deploying replica instances of Storyden.

AMQP_URL

type	string
default	amqp://guest:guest@localhost:5672/

The RabbitMQ URL to connect to.

This is a full URL with amqp:// as the scheme. You can set the username and password using the URL format, for example: amqp://<username>:<password>@<host>:<port>.

The default value is amqp://guest:guest@localhost:5672/ which is the default RabbitMQ URL.

Storyden does not currently support amqps:// (secure) URLs, but this will be added soon.

Artificial intelligence/language models

Configuration for optional AI features. These can be useful for organising large amounts of library pages and threads, but it can also provide other features such as recommendations and ask-based conversational searching.

LANGUAGE_MODEL_PROVIDER

type	string
default	none

The provider for language model features.

openai is currently the only supported provider.

OPENAI_API_KEY

type	string
default	none

When LANGUAGE_MODEL_PROVIDER is set to openai, this is the API key for the OpenAI API.

ASKER_PROVIDER

type	string
default	(empty string)

The Asker feature provides a conversational interface for exploring the community's content across library pages, threads, links, profiles, etc. It is separate from the language model provider as some providers support different features.

This can be set to either:

• openai for OpenAI
• perplexity for Perplexity AI - note that Perplexity does not currently support all the features necessary to be a LANGUAGE_MODEL_PROVIDER so it is only available as an ASKER_PROVIDER.

PERPLEXITY_API_KEY

type	string
default	none

If ASKER_PROVIDER is set to perplexity, this is the API key for the Perplexity API.

Semdex

The Semdex is a semantic index that provides vector-based storage of content. This is used for things like recommendations, search, etc.

The Semdex works with the language model provider to create embeddings of content. Thus, enabling the Semdex requires a LANGUAGE_MODEL_PROVIDER to be set.

SEMDEX_PROVIDER

type	string
default	(empty string)

Either:

• chromem for an experimental local vector database. This is not recommended for use in large deployments as it's rather slow and memory-hungry.
• weaviate for Weaviate, a self-hostable or managed vector database.
• pinecone for Pinecone, a fully managed vector database.

Local Semdex

Configuration for when SEMDEX_PROVIDER is set to chromem.

SEMDEX_LOCAL_PATH

type	string
default	data/semdex

The path to the directory where Chromem will store vector indexes.

Weaviate Semdex

Configuration for when SEMDEX_PROVIDER is set to weaviate.

WEAVIATE_URL

type	string
default	none

The Weaviate API URL. This can be set to a self-hosted instance of Weaviate or the Weaviate Cloud API.

WEAVIATE_API_TOKEN

type	string
default	none

For self-hosted Weaviate where authentication is enabled, or when using Weaviate Cloud.

WEAVIATE_CLASS_NAME

type	string
default	none

The class name for Weaviate. This value actually controls which model is used for embeddings and other configuration. In future, there will be a more flexible configuration for Weaviate.

Value values are:

• text2vec-transformers: requires that the Weaviate instance is using the text2vec-transformers module. This is for calculating embeddings locally using a GPU (or very slowly, using a CPU.) This is only available when self-hosting Weaviate.
• text2vec-openai: requires that the Weaviate instance is using the text2vec-openai module. This uses OpenAI's API to calculate embeddings. This works on both self-hosted and Weaviate Cloud instances.

Pinecone Semdex

Configuration for when SEMDEX_PROVIDER is set to pinecone.

PINECONE_API_KEY

type	string
default	none

Your Pinecone API key. This is required for all Pinecone API requests.

PINECONE_INDEX

type	string
default	none

The index name that Storyden will use in your Pinecone workspace.

PINECONE_DIMENSIONS

type	integer (e.g. 1, 2, 3)
default	none

This value is dependent on the underlying OpenAI configuration. Currently this is static and set to 3072 dimensions. In future, Storyden will provide more flexible configuration for language model providers.

PINECONE_CLOUD

type	string
default	none

Pinecone provides hosting on different cloud providers, see the Pinecone documentation for more information. The cloud provider you choose will be reflected in your Pinecone dashboard.

PINECONE_REGION

type	string
default	none

Same as above, but for the region. As with any third party providers, it's recommended to choose the region closest to both your Storyden deployment and your community members for best performance and experience.