MrDoc Deployment Guide
Quick Start
Docker Deployment
Docker Image Deployment
Docker Compose Deployment
Configure Guide
Configuration File Guide
Customizing uWSGI Configuration
Data Security
Site Data Backup / Site Migration
Data Export and Import
Open Source Edition → Professional Edition Data Migration
Troubleshooting
Server Requirements & Deployment Recommendations
Published with MrDoc Pro
-
+
home
Configuration File Guide
> w **⚠️ Warning** > If you edit the configuration file using Windows Notepad, be sure to save it as **UTF-8 without BOM**. MrDoc works out of the box without requiring configuration. At the same time, MrDoc supports customizing various site settings via configuration files. The configuration file is located in the `config` folder inside the project directory (`MrDoc` or `MrDocPro`), named `config.ini`. **==If this file does not exist, you can create it yourself.==** > d 💡 **Note:** If the application is already running, you must restart the application (or Docker container if deployed via Docker) after modifying the configuration file. --- ## Enable Site Debug Mode By default, the site runs in non-debug mode. To enable debug mode, add the following to the config file: ```ini [site] # True to enable debug mode; False to disable debug = True ``` After saving changes, restart the application or Docker container. --- ## Database Configuration By default, MrDoc uses SQLite as its database. If you want to use a different database, specify the database settings in the config file. > d ⚠️ Database must be configured **before** running `python manage.py makemigrations`; otherwise, existing data may be lost! > ⚠️ When changing databases after deployment, ensure you export and back up data to prevent data loss! ### Database Dependencies Installation > i ℹ️ The official Docker image already includes MySQL and PostgreSQL dependencies; no additional installation is needed when deploying via Docker. * PostgreSQL requires `psycopg` (PostgreSQL >= 12) * MySQL requires `mysqlclient` (MySQL >= 8.0) * Oracle requires `cx_Oracle` (Oracle >= 19c) Besides SQLite, MrDoc supports the following databases: * MySQL * Oracle * PostgreSQL Example configuration: ```ini [database] # Database engine: sqlite, mysql, oracle, or postgresql engine = mysql # Database name name = db_name # Database user user = db_user # Database password password = db_pwd # Database host host = db_host # Database port port = db_port ``` Restart the app/Docker container after changes. --- ## Site Language and Timezone Configuration > i ℹ️ Without setting `force = True`, browsers with different language preferences may display other languages, because Django (the framework behind MrDoc) uses its own mechanism for language detection and translation loading. See: [https://docs.djangoproject.com/en/4.2/topics/i18n/translation/#how-django-discovers-language-preference](https://docs.djangoproject.com/en/4.2/topics/i18n/translation/#how-django-discovers-language-preference) > If you want to force MrDoc to use a single language regardless of browser language, set `force = True`. Default language is Simplified Chinese (`zh-hans`), and timezone is `Asia/Shanghai`. Currently supported languages: * Simplified Chinese (zh-hans) * Traditional Chinese (zh-hant) * English (en) Example config to change language and timezone: ```ini [locale] language = en timezone = America/Chicago # Force the site to use the above language regardless of browser settings (default: False) force = True ``` Restart after modification. --- ## Session Configuration ```ini [session] # Session expiration time in seconds (default: one week) cookie_age = 604800 # Expire session on browser close (default: False) browser_close = True # Secure cookie flag (default: False) cookie_secure = False # HttpOnly flag (default: True) cookie_httponly = True ``` Restart after modification. --- ## PDF Download Configuration > i ℹ️ Official Docker runtime image includes required dependencies; no extra config needed. MrDoc includes a PDF export feature relying on Chromium and chromedriver. To enable PDF export, install Chromium or Chrome on the host machine, then configure: ```ini [selenium] # On Windows, if using/testing, set driver = Chrome; otherwise, omit driver = Chrome # If chromedriver is not auto-detected, specify its absolute path here driver_path = /path/to/chromedriver ``` Restart after modification. --- ## Allowed Image Upload Formats By default, MrDoc allows image uploads with extensions: `jpg,jpeg,gif,png,bmp,webp`. To customize allowed formats (comma-separated), configure: ```ini [image_upload] suffix_name = jpg,jpeg,gif,png,bmp,webp ``` > s ⚠️ Warning: Formats like SVG, which support embedded code, pose significant security risks. Use caution when enabling such formats. Restart after modification. --- ## Extended Media Directory By default, MrDoc serves user-uploaded media (images, attachments) from the `media` directory. If your documents use other directories for media, copy them into MrDoc’s root directory and configure: ```ini [extend_media] is_enable = True root_path = images ``` > Note: This is for temporary use only. New uploads still go to `media`. Restart after modification. --- ## CSRF Trusted Origins ```ini [csrf_origin] allow = hostname1,hostname2,https://example.com ``` Multiple hosts separated by commas. Restart after modification. --- ## CORS Allowed Origins ```ini [cors_origin] allow = http://example.com,http://192.168.1.1:8008 ``` Restart after modification. --- ## Enable IFrame Embedding Support By default, MrDoc disallows embedding inside cross-origin iframes. To allow embedding, configure: ```ini [x_frame] option = ALLOWALL ``` Restart after modification. --- ## Configuring Root-Level Text File Access In cases like domain verification, you may need to serve text files at the site root. Usually, this is better handled by Nginx, but MrDoc supports it as follows: 1. Place the text file(s) in the application’s `template` directory: * Open Source: `/MrDoc/template` * Pro Edition: `/MrDocPro/template` For Docker default paths: * Open Source: `/opt/MrDoc/template` * Pro Edition: `/opt/MrDocPro/template` 2. Configure in `config.ini`: ```ini [extend_root_txt] filename = ads.txt,other.txt ``` You can access the file at: `https://yourdomain.com/ads.txt` Restart after modification. --- ## Third-Party Cache Configuration By default, MrDoc uses in-memory cache. To configure other cache backends: ```ini [cache] backend = memcached|redis|filebase|locmem location = cache_connection_string_or_path ``` Supported backends: * `memcached` — Memcached server * `redis` — Redis server * `filebase` — Filesystem cache * `locmem` — Local memory cache ### Memcached example ```ini [cache] backend = memcached location = 127.0.0.1:11211 ``` ### Redis example ```ini [cache] backend = redis location = redis://user:password@127.0.0.1:6379 ``` ### Filesystem cache example ```ini [cache] backend = filebase location = /var/tmp/mrdoc_cache ``` --- ## Disable Sitemap By default, MrDoc enables the sitemap feature. To disable: ```ini [sitemap] status = False ``` Restart after modification. --- ## Attachment Preview (Pro Edition) > i ℹ️ No config needed for official Docker runtime image. ```ini [preview] # Path to LibreOffice executable (install LibreOffice on your server first) libreoffice_path = C://Program Files//LibreOffice//program//soffice.exe ``` LibreOffice installation instructions: [https://doc.mrdoc.pro/doc/44895/](https://doc.mrdoc.pro/doc/44895/) Restart after modification. --- ## Attachment Format Whitelist (Pro Edition) ```ini [attachment_suffix] # Enable whitelist validation: True = enable, False = disable (default: True) # Disabling stops validating allowed attachment formats is_enable = False ``` Restart after modification. --- ## Repository Account Configuration (Pro Edition) For Pro Edition, configure private repository credentials to enable version update checks: ```ini [liscense] git_user = your_username git_pwd = your_password ``` Restart after modification.
mrdoc
Nov. 18, 2025, 10:28 a.m.
Forward
Favorites
Last
Next
Scan the QR Code
Copy link
Scan the QR code to share.
Copy link
Markdown file
Word document
PDF document
PDF document (print)
share
link
type
password
Update password
Validity period