Release

.env.example

@@ -1,14 +1,24 @@
+# This file, when named as ".env" in the root of your BookStack install
+# folder, is used for the core configuration of the application.
+# By default this file contains the most common required options but
+# a full list of options can be found in the '.env.example.complete' file.
+
+# NOTE: If any of your values contain a space or a hash you will need to
+# wrap the entire value in quotes. (eg. MAIL_FROM_NAME="BookStack Mailer")
+
 # Application key
 # Used for encryption where needed.
 # Run `php artisan key:generate` to generate a valid key.
 APP_KEY=SomeRandomString
 
 # Application URL
-# Remove the hash below and set a URL if using BookStack behind
-# a proxy, if using a third-party authentication option.
 # 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
+# All URLs in BookStack will be generated using this value
+# to ensure URLs generated are consistent and secure.
+# If you change this in the future you may need to run a command
+# to update stored URLs in the database. Command example:
+# php artisan bookstack:update-url https://old.example.com https://new.example.com
+APP_URL=https://example.com
 
 # Database details
 DB_HOST=localhost
@@ -20,16 +30,17 @@ DB_PASSWORD=database_user_password
 # Can be 'smtp' or 'sendmail'
 MAIL_DRIVER=smtp
 
-# Mail sender options
-MAIL_FROM_NAME=BookStack
+# Mail sender details
+MAIL_FROM_NAME="BookStack"
 [email protected]
 
 # SMTP mail options
+# These settings can be checked using the "Send a Test Email"
+# feature found in the "Settings > Maintenance" area of the system.
+# For more detailed documentation on mail options, refer to:
+# https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration
 MAIL_HOST=localhost
-MAIL_PORT=1025
+MAIL_PORT=587
 MAIL_USERNAME=null
 MAIL_PASSWORD=null
 MAIL_ENCRYPTION=null
-
-
-# A full list of options can be found in the '.env.example.complete' file.

.env.example.complete

@@ -3,6 +3,10 @@
 # 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
@@ -42,6 +46,14 @@ APP_TIMEZONE=UTC
 # 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.
 DB_HOST=localhost
@@ -50,20 +62,27 @@ DB_DATABASE=database_database
 DB_USERNAME=database_username
 DB_PASSWORD=database_user_password
 
-# Mail system to use
-# Can be 'smtp', 'mail' or 'sendmail'
-MAIL_DRIVER=smtp
+# 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 sending options
-[email protected]
+# Mail configuration
+# Refer to https://www.bookstackapp.com/docs/admin/email-webhooks/#email-configuration
+MAIL_DRIVER=smtp
+[email protected]
 MAIL_FROM_NAME=BookStack
 
-# SMTP mail options
 MAIL_HOST=localhost
-MAIL_PORT=1025
+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'
@@ -92,8 +111,7 @@ MEMCACHED_SERVERS=127.0.0.1:11211:100
 REDIS_SERVERS=127.0.0.1:6379:0
 
 # Queue driver to use
-# Queue not really currently used but may be configurable in the future.
-# Would advise not to change this for now.
+# Can be 'sync', 'database' or 'redis'
 QUEUE_CONNECTION=sync
 
 # Storage system to use
@@ -126,9 +144,13 @@ STORAGE_S3_ENDPOINT=https://my-custom-s3-compatible.service.com:8001
 STORAGE_URL=false
 
 # Authentication method to use
-# Can be 'standard', 'ldap' or 'saml2'
+# 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/
@@ -193,12 +215,15 @@ LDAP_SERVER=false
 LDAP_BASE_DN=false
 LDAP_DN=false
 LDAP_PASS=false
-LDAP_USER_FILTER=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
 
@@ -207,6 +232,7 @@ LDAP_DUMP_USER_DETAILS=false
 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/
@@ -221,13 +247,36 @@ 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
@@ -238,22 +287,64 @@ DISABLE_EXTERNAL_SERVICES=false
 # Example: AVATAR_URL=https://seccdn.libravatar.org/avatar/${hash}?s=${size}&d=identicon
 AVATAR_URL=
 
-# Enable draw.io integration
+# Enable diagrams.net integration
 # Can simply be true/false to enable/disable the integration.
-# Alternatively, It can be URL to the draw.io instance you want to use.
-# For URLs, The following URL parameters should be included: embed=1&proto=json&spin=1
+# 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'
+# 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=50
+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 <script> tags in page content
 # Note, if set to 'true' the page editor may still escape scripts.
@@ -265,9 +356,53 @@ ALLOW_CONTENT_SCRIPTS=false
 # 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 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
+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

.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: [ssddanbrown]
+ko_fi: ssddanbrown

.github/ISSUE_TEMPLATE/api_request.yml

@@ -0,0 +1,25 @@
+name: New API Endpoint or API Ability
+description: Request a new endpoint or API feature be added
+labels: [":nut_and_bolt: API Request"]
+body:
+  - type: textarea
+    id: feature
+    attributes:
+      label: API Endpoint or Feature
+      description: Clearly describe what you'd like to have added to the API.
+    validations:
+      required: true
+  - type: textarea
+    id: usecase
+    attributes:
+      label: Use-Case
+      description: Explain the use-case that you're working-on that requires the above request.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Add any other context about the feature request here.
+    validations:
+      required: false