From 6d6b5d19fa15f023998ead996b9a8d56d13001c2 Mon Sep 17 00:00:00 2001 From: Pascal Riemer <155780777+pascalriemer@users.noreply.github.com> Date: Tue, 4 Mar 2025 15:54:06 +0100 Subject: [PATCH] Improve docker-compose.env with missing variables and explanations This PR updates the docker-compose.env file in the Paperless-ngx documentation to provide a more complete and user-friendly reference for environment variables. ## Changes: - Added several missing environment variables based on the official Paperless-ngx configuration docs. - Included explanations for each variable, keeping the style consistent with the existing file. - Added links to relevant external documentation (e.g., Django docs) where applicable. ## Why this change? I self-host over 30 services and am used to example .env files in GitHub repositories providing a complete list of configurable options. When setting up Paperless-ngx, I initially overlooked the comment at the top of the file referencing the official configuration docs ("# See http://docs.paperless-ngx.com/configuration/ for all available options.") This short comment is a bit hidden within a block of other metadata, and I only realized later that many available variables were missing from the example file. This update aims to: - Improve clarity and discoverability of Paperless-ngx settings. - Reduce confusion for users who, like me, expect docker-compose.env to be a full reference. - Provide a more practical and self-contained starting point for Docker Compose users. This expanded docker-compose.env should make it easier to configure Paperless-ngx effectively while keeping the documentation aligned with the official sources. --- docker/compose/docker-compose.env | 204 ++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) diff --git a/docker/compose/docker-compose.env b/docker/compose/docker-compose.env index 7563ec069..f43292070 100644 --- a/docker/compose/docker-compose.env +++ b/docker/compose/docker-compose.env @@ -19,6 +19,8 @@ # Adjust this key if you plan to make paperless available publicly. It should # be a very long sequence of random characters. You don't need to remember it. +# This is used by Django for session management, and should be kept secret. +# See https://docs.djangoproject.com/en/stable/ref/settings/#secret-key for more information. #PAPERLESS_SECRET_KEY=change-me # Use this variable to set a timezone for the Paperless Docker containers. Defaults to UTC. @@ -35,3 +37,205 @@ # See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names&suite=buster # for available languages. #PAPERLESS_OCR_LANGUAGES=tur ces + +# This setting allows to configure the broker url used by celery. +# For a redis broker: redis://user:password@host:port/db_number +#PAPERLESS_REDIS=redis://redis:6379/0 + +# The location where paperless stores uploaded documents awaiting processing. +#PAPERLESS_CONSUMPTION_DIR=/usr/src/paperless/consume + +# The location where paperless stores processed documents. +#PAPERLESS_DATA_DIR=/usr/src/paperless/data + +# Location for media files (uploaded document originals and thumbnails) +#PAPERLESS_MEDIA_DIR=/usr/src/paperless/media + +# The directory to which paperless exports documents. +#PAPERLESS_EXPORT_DIR=/usr/src/paperless/export + +# Whether to allow users to register themselves. Defaults to false. +#PAPERLESS_ALLOW_REGISTRATION=false + +# The default name to use for the superuser account, defaults to 'paperless'. +#PAPERLESS_ADMIN_USER=paperless + +# The default email address to use for the superuser account, defaults to 'paperless@example.com'. +#PAPERLESS_ADMIN_MAIL=paperless@example.com + +# The default password to use for the superuser account. This is not secure if you expose paperless. +# Always change this password using the web UI or manage.py createsuperuser. +#PAPERLESS_ADMIN_PASSWORD=paperless + +# Adjust this to configure the number of worker processes used by the document +# consumer. More workers means faster document processing, but also higher CPU +# and memory usage. Defaults to the number of cores available to the container. +#PAPERLESS_WORKERS=2 + +# Adjust this to configure the number of threads used by the OCR backend. +# More threads means faster OCR processing, but also higher CPU and memory usage. +# Defaults to the number of cores available to the container. +#PAPERLESS_OCR_THREADS=2 + +# Enables or disables asynchronous tasks. Defaults to true. If disabled, +# tasks are executed inline, which can simplify debugging but may impact +# performance. +#PAPERLESS_TASK_ASYNCHRONOUS=true + +# Sets the logging level. Defaults to INFO. Options are DEBUG, INFO, WARNING, ERROR, CRITICAL. +#PAPERLESS_LOG_LEVEL=INFO + +# This setting allows you to customize the algorithm used for matching documents during import. +# The default is 'fuzzy', which uses fuzzy matching. Other options include 'exact' for exact filename matching and 'none' to disable matching. +#PAPERLESS_FILENAME_MATCHING_ALGORITHM=fuzzy + +# Sets the confidence threshold for OCR results. Values below this threshold are discarded. +#PAPERLESS_OCR_TEXT_PAGE_CONFIDENCE=60 + +# Enable or disable automatic document renaming. Defaults to true. +#PAPERLESS_RENAME_FILES=true + +# Defines the naming scheme used when renaming files. Uses Django template syntax. +# See https://docs.djangoproject.com/en/stable/ref/templates/language/ for details on the template syntax. +#PAPERLESS_FILENAME_FORMAT={% if document.correspondent %}{{ document.correspondent }} - {% endif %}{{ document.created|date:"%Y-%m-%d" }} - {{ document.title }} + +# When set to true, unpaper will be used to clean scanned documents. This can improve OCR quality. +#PAPERLESS_UNPAPER=false + +# Defines whether to automatically rotate pages based on detected text orientation. Defaults to true. +#PAPERLESS_AUTO_ROTATE=true + +# Defines whether to automatically split merged documents into individual files. Defaults to false. +#PAPERLESS_AUTO_SPLIT=false + +# Comma-separated list of tags to apply to all imported documents. +#PAPERLESS_DEFAULT_TAGS=tag1,tag2 + +# Comma-separated list of users and groups that have view permissions. +# The user and group names can be the Paperless usernames or group names, or +# can be an ID number. To find the ID number, you can use the Django shell, +# as well as the admin panel. If this variable is not set, all users can +# view all documents. +#PAPERLESS_SHARED_LINK_VIEW_USERS=user1,group1 + +# Define which database engine to use. The default is 'postgres'. Other options include 'mysql' and 'sqlite'. +#PAPERLESS_DATABASE_ENGINE=postgres + +# The database name. Defaults to 'paperless'. +#PAPERLESS_DATABASE_NAME=paperless + +# The database user. Defaults to 'paperless'. +#PAPERLESS_DATABASE_USER=paperless + +# The database password. +#PAPERLESS_DATABASE_PASSWORD=paperless + +# The database host. +#PAPERLESS_DATABASE_HOST=db + +# The database port. +#PAPERLESS_DATABASE_PORT=5432 + +# The database SSL mode. Defaults to 'require'. Other options include 'disable', 'allow', 'prefer', 'verify-ca', 'verify-full'. +# See https://www.postgresql.org/docs/current/libpq-ssl.html for details. +#PAPERLESS_DATABASE_SSL_MODE=require + +# Time in seconds to cache document thumbnails. Set to 0 to disable caching. Defaults to 60*60*24*7 (7 days). +#PAPERLESS_THUMBNAIL_CACHE_TIME=604800 + +# The number of documents to display per page in the user interface. Defaults to 25. +#PAPERLESS_PAGE_SIZE=25 + +# If enabled, Paperless will update its document index after a document has been processed. +# Disabling this can improve performance if you are importing a large number of documents, but +# you will need to manually run the management command "document_index" after the import is complete. +#PAPERLESS_UPDATE_INDEX_ON_SAVE=true + +# Set this to True to enable the health check endpoint at /api/health/. Defaults to False. +#PAPERLESS_ENABLE_HEALTH_CHECK=false + +# The port the webserver listens on. Defaults to 8000. +#PAPERLESS_PORT=8000 + +# The user ID for the process running paperless. If set, paperless will attempt to switch to this user. Requires root privileges. +#PAPERLESS_UID=1000 + +# The group ID for the process running paperless. If set, paperless will attempt to switch to this group. Requires root privileges. +#PAPERLESS_GID=1000 + +# List of directories to scan recursively for document files to consume. Can be multiple directories separated by colon (:). +#PAPERLESS_ADDITIONAL_CONSUMPTION_DIRECTORIES=/path/to/additional/consume:/another/path + +# Enable or disable original document deletion after successful consumption. Defaults to false. +#PAPERLESS_DELETE_AFTER_CONSUMPTION=false + +# If enabled, Paperless will attempt to correct the orientation of documents during consumption. +# Requires the 'tesseract' command to be available in the path. Defaults to true. +#PAPERLESS_CORRECT_ORIENTATION=true + +# Enable or disable automatic tag matching during consumption. If enabled, Paperless will attempt +# to automatically apply tags to documents based on their content. Defaults to true. +#PAPERLESS_TAG_MATCHING=true + +# Enable or disable document type matching during consumption. If enabled, Paperless will attempt +# to automatically set the document type based on the content. Defaults to true. +#PAPERLESS_DOCUMENT_TYPE_MATCHING=true + +# Enable or disable storage path matching during consumption. If enabled, Paperless will attempt +# to automatically set the storage path based on the content. Defaults to true. +#PAPERLESS_STORAGE_PATH_MATCHING=true + +# The URL of your SMTP server. Required if you want to send email notifications. +#PAPERLESS_SMTP_HOST=smtp.example.com + +# The port of your SMTP server. Defaults to 587. +#PAPERLESS_SMTP_PORT=587 + +# The username for your SMTP server. +#PAPERLESS_SMTP_USER=user@example.com + +# The password for your SMTP server. +#PAPERLESS_SMTP_PASSWORD=password + +# Whether to use TLS for SMTP connections. Defaults to True. +#PAPERLESS_SMTP_TLS=true + +# Whether to use SSL for SMTP connections. Defaults to False. +#PAPERLESS_SMTP_SSL=false + +# The email address to send notifications from. +#PAPERLESS_EMAIL_FROM_ADDRESS=paperless@example.com + +# The template used to generate email subjects for consumed documents. Uses Django template syntax. +#PAPERLESS_EMAIL_SUBJECT_TEMPLATE=[Paperless] New document: {{document.title}} + +# The template used to generate email body for consumed documents. Uses Django template syntax. +#PAPERLESS_EMAIL_BODY_TEMPLATE=A new document has been consumed by Paperless-ngx.\n\nTitle: {{document.title}}\nCorrespondent: {{document.correspondent}}\nTags: {% for tag in document.tags.all %}{{tag.name}}{% if not forloop.last %}, {% endif %}{% endfor %}\nCreated: {{document.created}} + +# The format used to display dates in the user interface. Uses Python's strftime format. +# See https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior for format options. +#PAPERLESS_DATE_FORMAT=%Y-%m-%d + +# The format used to display date and time in the user interface. Uses Python's strftime format. +#PAPERLESS_DATETIME_FORMAT=%Y-%m-%d %H:%M:%S + +# Set this to True to enable debug mode. Enabling debug mode will expose sensitive information, so it should only be enabled in development environments. +#PAPERLESS_DEBUG=false + +# The default language to use for the user interface. Defaults to 'en'. +#PAPERLESS_UI_LANGUAGE=en + +# Set this to True to disable CSRF protection. Disabling CSRF protection makes your installation vulnerable to cross-site request forgery attacks and should only be done in controlled environments, like behind a reverse proxy that handles CSRF protection. It defaults to being enabled (False) if the PAPERLESS_URL setting is not set, and disabled (True) otherwise. +#PAPERLESS_CSRF_TRUSTED_ORIGINS= + +# The location where temporary files are stored. Defaults to /tmp. +#PAPERLESS_TEMP_DIR=/tmp + +# Enable or disable experimental features. Defaults to false. +#PAPERLESS_EXPERIMENTAL_FEATURES=false + +# The Redis URL to use for caching. If not specified, caching will be disabled. Redis is used for caching metadata of processed documents to improve loading times. +#PAPERLESS_CACHING_REDIS=redis://redis:6379/1 + +# The log level for Celery tasks. Defaults to INFO. +#PAPERLESS_CELERY_LOG_LEVEL=INFO