# Full list of environment variables that can be used with BookStack.

# Selectively copy these to your '.env' file as required.

# Each option is shown with it's default value.

# Do not copy this whole file to use as your '.env' file.

# The details here only serve as a quick reference.

# Please refer to the BookStack documentation for full details:

# https://www.bookstackapp.com/docs/

# Application environment

# Can be 'production', 'development', 'testing' or 'demo'

APP_ENV=production

# Enable debug mode

# Shows advanced debug information and errors.

# CAN EXPOSE OTHER VARIABLES, LEAVE DISABLED

APP_DEBUG=false

# Application key

# Used for encryption where needed.

# Run `php artisan key:generate` to generate a valid key.

APP_KEY=SomeRandomString

# Application URL

# This must be the root URL that you want to host BookStack on.

# All URL's in BookStack will be generated using this value.

APP_URL=https://example.com

# Application default language

# The default language choice to show.

# May be overridden by user-preference or visitor browser settings.

APP_LANG=en

# Auto-detect language for public visitors.

# Uses browser-sent headers to infer a language.

# APP_LANG will be used if such a header is not provided.

APP_AUTO_LANG_PUBLIC=true

# Application timezones

# The first option is used to determine what timezone is used for date storage.

# Leaving that as "UTC" is advised.

# The second option is used to set the timezone which will be used for date

# formatting and display. This defaults to the "APP_TIMEZONE" value.

# Valid timezone values can be found here: https://www.php.net/manual/en/timezones.php

APP_TIMEZONE=UTC

APP_DISPLAY_TIMEZONE=UTC

# Application theme

# Used to specific a themes/<APP_THEME> folder where BookStack UI

# overrides can be made. Defaults to disabled.

APP_THEME=false

# Trusted proxies

# Used to indicate trust of systems that proxy to the application so

# certain header values (Such as "X-Forwarded-For") can be used from the

# incoming proxy request to provide origin detail.

# Set to an IP address, or multiple comma seperated IP addresses.

# Can alternatively be set to "*" to trust all proxy addresses.

APP_PROXIES=null

# Database details

# Host can contain a port (localhost:3306) or a separate DB_PORT option can be used.

# An ipv6 address can be used via the square bracket format ([::1]).

DB_HOST=localhost

DB_PORT=3306

DB_DATABASE=database_database

DB_USERNAME=database_username

DB_PASSWORD=database_user_password

# MySQL specific connection options

# Path to Certificate Authority (CA) certificate file for your MySQL instance.

# When this option is used host name identity verification will be performed

# which checks the hostname, used by the client, against names within the

# certificate itself (Common Name or Subject Alternative Name).

MYSQL_ATTR_SSL_CA="/path/to/ca.pem"

# Mail configuration

# Refer to https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration

MAIL_DRIVER=smtp

MAIL_FROM=bookstack@example.com

MAIL_FROM_NAME=BookStack

MAIL_HOST=localhost

MAIL_PORT=587

MAIL_USERNAME=null

MAIL_PASSWORD=null

MAIL_ENCRYPTION=null

MAIL_VERIFY_SSL=true

MAIL_SENDMAIL_COMMAND="/usr/sbin/sendmail -bs"

# Cache & Session driver to use

# Can be 'file', 'database', 'memcached' or 'redis'

CACHE_DRIVER=file

SESSION_DRIVER=file

# Session configuration

SESSION_LIFETIME=120

SESSION_COOKIE_NAME=bookstack_session

SESSION_SECURE_COOKIE=false

# Cache key prefix

# Can be used to prevent conflicts multiple BookStack instances use the same store.

CACHE_PREFIX=bookstack

# Memcached server configuration

# If using a UNIX socket path for the host, set the port to 0

# This follows the following format: HOST:PORT:WEIGHT

# For multiple servers separate with a comma

MEMCACHED_SERVERS=127.0.0.1:11211:100

# Redis server configuration

# This follows the following format: HOST:PORT:DATABASE

# or, if using a password: HOST:PORT:DATABASE:PASSWORD

# For multiple servers separate with a comma. These will be clustered.

REDIS_SERVERS=127.0.0.1:6379:0

# Queue driver to use

# Can be 'sync', 'database' or 'redis'

QUEUE_CONNECTION=sync

# Storage system to use

# Can be 'local', 'local_secure' or 's3'

STORAGE_TYPE=local

# Image storage system to use

# Defaults to the value of STORAGE_TYPE if unset.

# Accepts the same values as STORAGE_TYPE.

STORAGE_IMAGE_TYPE=local

# Attachment storage system to use

# Defaults to the value of STORAGE_TYPE if unset.

# Accepts the same values as STORAGE_TYPE although 'local' will be forced to 'local_secure'.

STORAGE_ATTACHMENT_TYPE=local_secure

# Amazon S3 storage configuration

STORAGE_S3_KEY=your-s3-key

STORAGE_S3_SECRET=your-s3-secret

STORAGE_S3_BUCKET=s3-bucket-name

STORAGE_S3_REGION=s3-bucket-region

# S3 endpoint to use for storage calls

# Only set this if using a non-Amazon s3-compatible service such as Minio

STORAGE_S3_ENDPOINT=https://my-custom-s3-compatible.service.com:8001

# Storage URL prefix

# Used as a base for any generated image urls.

# An s3-format URL will be generated if not set.

STORAGE_URL=false

# Authentication method to use

# Can be 'standard', 'ldap', 'saml2' or 'oidc'

AUTH_METHOD=standard

# Automatically initiate login via external auth system if it's the only auth method.

# Works with saml2 or oidc auth methods.

AUTH_AUTO_INITIATE=false

# Social authentication configuration

# All disabled by default.

# Refer to https://www.bookstackapp.com/docs/admin/third-party-auth/

AZURE_APP_ID=false

AZURE_APP_SECRET=false

AZURE_TENANT=false

AZURE_AUTO_REGISTER=false

AZURE_AUTO_CONFIRM_EMAIL=false

DISCORD_APP_ID=false

DISCORD_APP_SECRET=false

DISCORD_AUTO_REGISTER=false

DISCORD_AUTO_CONFIRM_EMAIL=false

FACEBOOK_APP_ID=false

FACEBOOK_APP_SECRET=false

FACEBOOK_AUTO_REGISTER=false

FACEBOOK_AUTO_CONFIRM_EMAIL=false

GITHUB_APP_ID=false

GITHUB_APP_SECRET=false

GITHUB_AUTO_REGISTER=false

GITHUB_AUTO_CONFIRM_EMAIL=false

GITLAB_APP_ID=false

GITLAB_APP_SECRET=false

GITLAB_BASE_URI=false

GITLAB_AUTO_REGISTER=false

GITLAB_AUTO_CONFIRM_EMAIL=false

GOOGLE_APP_ID=false

GOOGLE_APP_SECRET=false

GOOGLE_SELECT_ACCOUNT=false

GOOGLE_AUTO_REGISTER=false

GOOGLE_AUTO_CONFIRM_EMAIL=false

OKTA_BASE_URL=false

OKTA_APP_ID=false

OKTA_APP_SECRET=false

OKTA_AUTO_REGISTER=false

OKTA_AUTO_CONFIRM_EMAIL=false

SLACK_APP_ID=false

SLACK_APP_SECRET=false

SLACK_AUTO_REGISTER=false

SLACK_AUTO_CONFIRM_EMAIL=false

TWITCH_APP_ID=false

TWITCH_APP_SECRET=false

TWITCH_AUTO_REGISTER=false

TWITCH_AUTO_CONFIRM_EMAIL=false

TWITTER_APP_ID=false

TWITTER_APP_SECRET=false

TWITTER_AUTO_REGISTER=false

TWITTER_AUTO_CONFIRM_EMAIL=false

# LDAP authentication configuration

# Refer to https://www.bookstackapp.com/docs/admin/ldap-auth/

LDAP_SERVER=false

LDAP_BASE_DN=false

LDAP_DN=false

LDAP_PASS=false

LDAP_USER_FILTER="(&(uid={user}))"

LDAP_VERSION=false

LDAP_START_TLS=false

LDAP_TLS_INSECURE=false

LDAP_TLS_CA_CERT=false

LDAP_ID_ATTRIBUTE=uid

LDAP_EMAIL_ATTRIBUTE=mail

LDAP_DISPLAY_NAME_ATTRIBUTE=cn

LDAP_THUMBNAIL_ATTRIBUTE=null

LDAP_FOLLOW_REFERRALS=true

LDAP_DUMP_USER_DETAILS=false

# LDAP group sync configuration

# Refer to https://www.bookstackapp.com/docs/admin/ldap-auth/

LDAP_USER_TO_GROUPS=false

LDAP_GROUP_ATTRIBUTE="memberOf"

LDAP_REMOVE_FROM_GROUPS=false

LDAP_DUMP_USER_GROUPS=false

# SAML authentication configuration

# Refer to https://www.bookstackapp.com/docs/admin/saml2-auth/

SAML2_NAME=SSO

SAML2_EMAIL_ATTRIBUTE=email

SAML2_DISPLAY_NAME_ATTRIBUTES=username

SAML2_EXTERNAL_ID_ATTRIBUTE=null

SAML2_IDP_ENTITYID=null

SAML2_IDP_SSO=null

SAML2_IDP_SLO=null

SAML2_IDP_x509=null

SAML2_ONELOGIN_OVERRIDES=null

SAML2_DUMP_USER_DETAILS=false

SAML2_AUTOLOAD_METADATA=false

SAML2_IDP_AUTHNCONTEXT=true

SAML2_SP_x509=null

SAML2_SP_x509_KEY=null

# SAML group sync configuration

# Refer to https://www.bookstackapp.com/docs/admin/saml2-auth/

SAML2_USER_TO_GROUPS=false

SAML2_GROUP_ATTRIBUTE=group

SAML2_REMOVE_FROM_GROUPS=false

# OpenID Connect authentication configuration

# Refer to https://www.bookstackapp.com/docs/admin/oidc-auth/

OIDC_NAME=SSO

OIDC_DISPLAY_NAME_CLAIMS=name

OIDC_CLIENT_ID=null

OIDC_CLIENT_SECRET=null

OIDC_ISSUER=null

OIDC_ISSUER_DISCOVER=false

OIDC_PUBLIC_KEY=null

OIDC_AUTH_ENDPOINT=null

OIDC_TOKEN_ENDPOINT=null

OIDC_USERINFO_ENDPOINT=null

OIDC_ADDITIONAL_SCOPES=null

OIDC_DUMP_USER_DETAILS=false

OIDC_USER_TO_GROUPS=false

OIDC_GROUPS_CLAIM=groups

OIDC_REMOVE_FROM_GROUPS=false

OIDC_EXTERNAL_ID_CLAIM=sub

OIDC_END_SESSION_ENDPOINT=false

# Disable default third-party services such as Gravatar and Draw.IO

# Service-specific options will override this option

DISABLE_EXTERNAL_SERVICES=false

# Use custom avatar service, Sets fetch URL

# Possible placeholders: ${hash} ${size} ${email}

# If set, Avatars will be fetched regardless of DISABLE_EXTERNAL_SERVICES option.

# Example: AVATAR_URL=https://seccdn.libravatar.org/avatar/${hash}?s=${size}&d=identicon

AVATAR_URL=

# Enable diagrams.net integration

# Can simply be true/false to enable/disable the integration.

# Alternatively, It can be URL to the diagrams.net instance you want to use.

# For URLs, The following URL parameters should be included: embed=1&proto=json&spin=1&configure=1

DRAWIO=true

# Default item listing view

# Used for public visitors and user's without a preference.

# Can be 'list' or 'grid'.

APP_VIEWS_BOOKS=list

APP_VIEWS_BOOKSHELVES=grid

APP_VIEWS_BOOKSHELF=grid

# Use dark mode by default

# Will be overriden by any user/session preference.

APP_DEFAULT_DARK_MODE=false

# Page revision limit

# Number of page revisions to keep in the system before deleting old revisions.

# If set to 'false' a limit will not be enforced.

REVISION_LIMIT=100

# Recycle Bin Lifetime

# The number of days that content will remain in the recycle bin before

# being considered for auto-removal. It is not a guarantee that content will

# be removed after this time.

# Set to 0 for no recycle bin functionality.

# Set to -1 for unlimited recycle bin lifetime.

RECYCLE_BIN_LIFETIME=30

# File Upload Limit

# Maximum file size, in megabytes, that can be uploaded to the system.

FILE_UPLOAD_SIZE_LIMIT=50

# Export Page Size

# Primarily used to determine page size of PDF exports.

# Can be 'a4' or 'letter'.

EXPORT_PAGE_SIZE=a4

# Export PDF Command

# Set a command which can be used to convert a HTML file into a PDF file.

# When false this will not be used.

# String values represent the command to be called for conversion.

# Supports '{input_html_path}' and '{output_pdf_path}' placeholder values.

# Example: EXPORT_PDF_COMMAND="/scripts/convert.sh {input_html_path} {output_pdf_path}"

EXPORT_PDF_COMMAND=false

# Export PDF Command Timeout

# The number of seconds that the export PDF command will run before a timeout occurs.

# Only applies for the EXPORT_PDF_COMMAND option, not for DomPDF or wkhtmltopdf.

EXPORT_PDF_COMMAND_TIMEOUT=15

# Set path to wkhtmltopdf binary for PDF generation.

# Can be 'false' or a path path like: '/home/bins/wkhtmltopdf'

# When false, BookStack will attempt to find a wkhtmltopdf in the application

# root folder then fall back to the default dompdf renderer if no binary exists.

# Only used if 'ALLOW_UNTRUSTED_SERVER_FETCHING=true' which disables security protections.

WKHTMLTOPDF=false

# Allow JavaScript, and other potentiall dangerous content in page content.

# This also removes CSP-level JavaScript control.

# Note, if set to 'true' the page editor may still escape scripts.

# DEPRECATED: Use 'APP_CONTENT_FILTERING' instead as detailed below. Activiting this option

# effectively sets APP_CONTENT_FILTERING='' (No filtering)

ALLOW_CONTENT_SCRIPTS=false

# Control the behaviour of content filtering, primarily used for page content.

# This setting is a string of characters which represent different available filters:

# - j - Filter out JavaScript and unknown binary data based content

# - h - Filter out unexpected, and potentially dangerous, HTML elements

# - f - Filter out unexpected form elements

# - a - Run content through a more complex allowlist filter

# This defaults to using all filters, unless ALLOW_CONTENT_SCRIPTS is set to true in which case no filters are used.

# Note: These filters are a best-attempt and may not be 100% effective. They are typically a layer used in addition to other security measures.

# Note: The default value will always be the most-strict, so it's advised to leave this unset in your own configuration

# to ensure you are always using the full range of filters.

APP_CONTENT_FILTERING="jfha"

# Indicate if robots/crawlers should crawl your instance.

# Can be 'true', 'false' or 'null'.

# The behaviour of the default 'null' option will depend on the 'app-public' admin setting.

# Contents of the robots.txt file can be overridden, making this option obsolete.

ALLOW_ROBOTS=null

# Allow server-side fetches to be performed to potentially unknown

# and user-provided locations. Primarily used in exports when loading

# in externally referenced assets.

# Can be 'true' or 'false'.

ALLOW_UNTRUSTED_SERVER_FETCHING=false

# A list of hosts that BookStack can be iframed within.

# Space separated if multiple. BookStack host domain is auto-inferred.

# For Example: ALLOWED_IFRAME_HOSTS="https://example.com https://a.example.com"

# Setting this option will also auto-adjust cookies to be SameSite=None.

ALLOWED_IFRAME_HOSTS=null

# A list of sources/hostnames that can be loaded within iframes within BookStack.

# Space separated if multiple. BookStack host domain is auto-inferred.

# Can be set to a lone "*" to allow all sources for iframe content (Not advised).

# Defaults to a set of common services.

# Current host and source for the "DRAWIO" setting will be auto-appended to the sources configured.

ALLOWED_IFRAME_SOURCES="https://*.draw.io https://*.youtube.com https://*.youtube-nocookie.com https://*.vimeo.com"

# A list of sources/hostnames that can be loaded as CSS styles within BookStack.

# Space separated if multiple. BookStack host domain is auto-inferred.

# Defaults to a permissive set if not provided.

# Example: ALLOWED_STYLE_SOURCES="https://fonts.googleapis.com"

ALLOWED_STYLE_SOURCES=null

# A list of sources/hostnames that can be loaded as image content within BookStack.

# Space separated if multiple. BookStack host domain is auto-inferred, in addition to

# data and blob images, due to their use for various functionality.

# Defaults to a permissive set if not provided.

# Example: ALLOWED_IMAGE_SOURCES="https://images.example.com"

ALLOWED_IMAGE_SOURCES=null

# A list of the sources/hostnames that can be reached by application SSR calls.

# This is used wherever users can provide URLs/hosts in-platform, like for webhooks.

# Host-specific functionality (usually controlled via other options) like auth

# or user avatars for example, won't use this list.

# Space seperated if multiple. Can use '*' as a wildcard.

# Values will be compared prefix-matched, case-insensitive, against called SSR urls.

# Defaults to allow all hosts.

ALLOWED_SSR_HOSTS="*"

# The default and maximum item-counts for listing API requests.

API_DEFAULT_ITEM_COUNT=100

API_MAX_ITEM_COUNT=500

# The number of API requests that can be made per minute by a single user.

API_REQUESTS_PER_MIN=180

# Enable the logging of failed email+password logins with the given message.

# The default log channel below uses the php 'error_log' function which commonly

# results in messages being output to the webserver error logs.

# The message can contain a %u parameter which will be replaced with the login

# user identifier (Username or email).

LOG_FAILED_LOGIN_MESSAGE=false

LOG_FAILED_LOGIN_CHANNEL=errorlog_plain_webserver

# Alter the precision of IP addresses stored by BookStack.

# Should be a number between 0 and 4, where 4 retains the full IP address

# and 0 completely hides the IP address. As an example, a value of 2 for the

# IP address '146.191.42.4' would result in '146.191.x.x' being logged.

# For the IPv6 address '2001:db8:85a3:8d3:1319:8a2e:370:7348' this would result as:

# '2001:db8:85a3:8d3:x:x:x:x'

IP_ADDRESS_PRECISION=4