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.