BookWyrm requires certain environment (ENV) variables in order to run correctly. These are set from a file named .env in the directory you run BookWyrm from. You will find most of these variabled described in the .env.example file in the main code repository. You should copy this as the basis of your .env file.
BookWyrm instance administrators should carefully check version release notes for any changes or additions to environment variables.
BookWyrm developers should prefer to use site.settings for configuration rather than ENV values if possible.
Learn more about each of these in the Django reference documentation.
ALLOWED_HOSTSA list of strings representing the host/domain names that this site can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server configurations.
The default is to allow all hosts, but you should usually change this. e.g. "localhost,bookwyrm.example.com"
MEDIA_ROOTimagesAbsolute filesystem path to the directory that will hold user-uploaded files. If running with Docker, remember that this is the directory location inside your container, not the host machine.
SECRET_KEY"7(2w1sedok=aznpq)ta1mc4i%4h=xx@hxwx*o57ctsuml0x%fr"A secret key for a particular BookWyrm instance. This is used to provide cryptographic signing, and should be set to a unique, unpredictable and long string.
If you do not change the SECRET_KEY from .env.example BookWyrm will throw an error and refuse to start.
STATIC_ROOTstaticThe absolute path to the directory where collectstatic will collect static files for deployment. If running with Docker, remember that this is the directory location inside your container, not the host machine.
DEBUGtrueDEBUG provides useful error information in the web interface for debugging on development servers.
This should be set to false on production instances. Never deploy a site into production without setting DEBUG to false!
NOTE: For version 0.7.5 and earlier, DEBUG defaulted to true.
LANGUAGE_CODE"en-us"A string representing the default language code for this installation.
SESSION_COOKIE_AGE2592000Time before being logged out (in seconds). The default is equivalent to 30 days. In future this default is likely to change to 1 year.
DATA_UPLOAD_MAX_MEMORY_MiB100Maximum allowed memory for file uploads. You can increase this if users are having trouble uploading BookWyrm export files. The real Django setting is DATA_UPLOAD_MAX_MEMORY_SIZE, however we use this setting in .env to allow instance admins to set the value in mebibytes rather than bytes.
DEFAULT_LANGUAGEEnglishBooks will rank higher in search results on this instance if one of their language values matches this value.
DOMAINThe fully qualified domain name for your site. Do not include a protocol or port numbers. e.g. example.com or subdomain.example.com.
EMAILUsed in the production branch's docker-compose.yml file as the email to send to Certbot.
PORT80 or 443 depending on value of USE_HTTPSThe port used to communicate with the web. Note that this is different to Django's PORT.
USE_HTTPSDEBUGIndicates whether or not your site uses HTTPS (SSL) – this affects which port BookWyrm uses and whether cookies are secured. Never run a production site without HTTPS!. This should always be set to true unless you are running a development server for testing.
These configurations may be moved to site.settings in future.
SEARCH_TIMEOUT8The total time in seconds that the instance will spend searching connectors.
QUERY_TIMEOUT5Timeout for a query to an individual connector.
The primary database for BookWyrm uses Postgres.
PGPORT5432The port to connect to the Postgres server. Same as Django's PORT.
POSTGRES_PASSWORDbookwyrmPassword for the database. Set this to a strong password string between quotation marks to avoid problems with certain characters being misinterpreted.
Do not use either of the default values from .env or settings.py as they are publicly known.
POSTGRES_USERbookwyrmThe name of your database user. Same as Django's USER.
POSTGRES_DBbookwyrmThe name of your database.
POSTGRES_HOSTlocalhostThe host server for your database. If not set or a blank string, defaults to localhost. Same as Django's HOST.
Redis is used to manage both activity streams and background jobs.
MAX_STREAM_LENGTH200The maximum length for Redis streams. If a stream grows longer than this, Redis will discard the oldest items in order to not exceed the MAX_STREAM_LENGTH.
See the Redis XTRIM documentation for more detail.
REDIS_ACTIVITY_HOSTlocalhostRedis server host. If not set, this defaults to localhost but if you are using Docker it should usually be set to redis_activity so that you are using the Redis container of that name.
REDIS_ACTIVITY_PORT6379The port your Redis server uses.
REDIS_ACTIVITY_PASSWORDPassword for your Redis database.
REDIS_ACTIVITY_DB_INDEXIf you are not using the default Docker setup with a separate Redis server for activity streams, you should set the REDIS_ACTIVITY_DB_INDEX to indicate which Redis database is being used for BookWyrm activity streams.
REDIS_ACTIVITY_URLIf you are using an external Redis database or want to use a unix socket, you can override all the other Redis settings by explictly setting the full REDIS_ACTIVITY_URL.
e.g. "redis://username:top_secret_pass@example.com:6380/0"
REDIS_BROKER_HOSTlocalhostRedis Celery server host. If not set this defaults to localhost but if using Docker should usually be set to redis_broker so that you are using the Redis container of that name.
REDIS_BROKER_PORT6379The port your Redis Celery server uses.
REDIS_BROKER_PASSWORDPassword for your Redis Celery database.
REDIS_BROKER_DB_INDEXIf you are not using the default Docker setup with a separate Redis server for Celery, you should set the REDIS_ACTIVITY_DB_INDEX to indicate which Redis database is being used for BookWyrm activity streams.
REDIS_BROKER_URLIf you are using an external Redis database or want to use a unix socket, you can override all the other Redis settings for your Celery database by explictly setting the full REDIS_BROKER_URL.
e.g. "redis://username:top_secret_pass@example.com:6380/0"
Flower provides a web UI for monitoring Celery tasks.
FLOWER_PORT8888Port for Flower site used to monitor Celery at https://example.com/flower.
FLOWER_USERThe user for your Flower interface.
FLOWER_PASSWORDThe password for your Flower monitoring interface. Flower can see all messages passing through your server so it is important that you set this to a strong, unique password and keep it secure.
EMAIL_HOSTThe smtp address of your email host. e.g. smtp.mailgun.org. Always check the terms and conditions of your email provider before using them for sending large volumes of mail. You probably need something like Mailgun.
EMAIL_PORT587The port for your email provider's smtp server.
EMAIL_HOST_USERThe username for your email provider. Usually in the form of a full email address e.g. mail@your.domain.here
EMAIL_HOST_PASSWORDThe password for your email provider account.
EMAIL_USE_TLStrueWhether your smtp connection uses TLS. Check that you are using the correct EMAIL_PORT for this.
EMAIL_USE_SSLfalseWhether your smtp connection uses SSL. Check that you are using the correct EMAIL_PORT for this.
EMAIL_SENDER_NAMEadminThe first part of the email address for emails sent by your BookWyrm instance. e.g. admin@example.com.
EMAIL_SENDER_DOMAINDOMAINThe domain of the email address for emails sent by your BookWyrm instance. e.g. admin@example.com.
USE_S3falseS3_SIGNED_URL_EXPIRY900Number of seconds before signed S3 urls expire. This is currently only used for user export files. This should only be as long as is required for a user download to complete once the user has clicked on the "download" button after the export has been processed.
AWS_ACCESS_KEY_IDAccess key for S3 storage of all types.
AWS_SECRET_ACCESS_KEYSecret key for S3 storage of all types.
AWS_STORAGE_BUCKET_NAMEThe bucket name you are using. e.g. "example-bucket-name"
AWS_S3_REGION_NAMEThe S3 region name. e.g. "eu-west-1" for AWS, "fr-par" for Scaleway, "nyc3" for Digital Ocean or "cluster-id" for Linode.
AWS_S3_CUSTOM_DOMAINThe domain that will serve the assets. e.g. "example-bucket-name.s3.fr-par.scw.cloud"
AWS_S3_URL_PROTOCOLPROTOCOL plus a colon e.g. "http:"Protocol for your S3 storage. Defaults to https: in production. You do not need to set this unless you want to override the default behaviour.
AWS_S3_ENDPOINT_URLThe S3 API endpoint. e.g. "https://s3.fr-par.scw.cloud"
These values are required if you are using Azure Blob Storage.
USE_AZUREfalseAZURE_ACCOUNT_NAMEe.g. "example-account-name"
AZURE_ACCOUNT_KEYe.g. "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="
AZURE_CONTAINERThe unique name for your container. e.g. "example-blob-container-name".
AZURE_CUSTOM_DOMAINYou can use a custom domain with Azure blob storage but this is not required. e.g. "example-account-name.blob.core.windows.net".
Some of these configuration values may be moved to site.settings in future.
ENABLE_THUMBNAIL_GENERATIONfalseWhether to enable generation of thumbnail images for book covers. Setting this to true will provide a boost to performance in terms of rendering images, however it comes at the price of 4-5 times more file storage required for book covers. For this reason it is set to false by default.
ENABLE_PREVIEW_IMAGESfalseThis setting allows the server to generate preview images that can be used as OpenGraph images (or Twitter card image). These previews are generated for the book (every time the title, cover or author changes, or a new public review with rating is published), the user (every time the name or avatar is changed), and the website (every time the site name, tagline or logo are changed). See Optional Features for more information.
PREVIEW_BG_COLORuse_dominant_color_lightThe background color for preview images. You can specify RGB tuple or RGB hex strings, or use_dominant_color_light / use_dominant_color_dark.
PREVIEW_TEXT_COLOR#363636The text color for preview images. If PREVIEW_BG_COLOR is use_dominant_color_dark, this should be set to #fff.
PREVIEW_IMG_WIDTH1200Width for preview images, in pixels.
PREVIEW_IMG_HEIGHT630Height for preview images, in pixels.
PREVIEW_DEFAULT_COVER_COLOR#002549If there is no cover image for a book, we create a default cover. This setting determines the color of that default book cover.
PREVIEW_DEFAULT_FONTSource Han SansIf there is no cover image for a book, we create a default cover. This setting determines the font used on that default book cover.
Use these settings to enable automatically sending telemetry to an OTLP-compatible service. Many of the main monitoring apps have OLTP collectors, including NewRelic, DataDog, and Honeycomb.io - consult their documentation for setup instructions.
OTEL_EXPORTER_OTLP_ENDPOINTAPI endpoint for your provider.
OTEL_EXPORTER_OTLP_HEADERSAny headers required, usually authentication information.
OTEL_SERVICE_NAMEService name is an arbitrary tag that is attached to any data sent, used to distinguish different sources. It can be useful for sending prod and dev metrics to the same place and keeping them separate, for instance.
HTTP_X_FORWARDED_PROTOfalseSetting this to true can compromise your site’s security. Ensure you fully understand your setup before changing it.
Only use it if your proxy is "swallowing" whether the original request was made via https. Please refer to the Django Documentation and assess the risks for your instance.
CSP_ADDITIONAL_HOSTSAdditional hosts to allow in the Content-Security-Policy, "self" (should be DOMAIN with optionally ":" + PORT) and AWS_S3_CUSTOM_DOMAIN (if used) are added by default. Value should be a comma-separated list of host names.
Some of these configuration values may be moved to site.settings in future.
TWO_FACTOR_LOGIN_VALIDITY_WINDOW2Sets the number of codes either side of which will be accepted. This should be a low number but you can increase it if your users are experiencing high network latency and their codes are expiring before they can complete the login process. With the default settings for this and TWO_FACTOR_LOGIN_MAX_SECONDS, users have up to 180 seconds to use a given login code and can use a valid code up to two before the current one.
TWO_FACTOR_LOGIN_MAX_SECONDS60Time in seconds for which a user login code is valid.