Home A - Z
Menu

An Otter Wiki

Blame

34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
1 
# Configuration
2
4c6b41 Ralph Thesen 2023-12-04 13:05:43
Added link to the installaton guide.
3
The [[Installation Guide|Installation]] can be found [[here|Installation]].
4
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
5
An Otter Wiki is configured in the application via the <i class="fas fa-cogs"></i>
5819b3 Ralph Thesen 2024-09-03 23:00:52
added documentation about the priorities of the settings sources This was discussed in https://github.com/redimp/otterwiki/issues/135
6
**Settings** interface as admin user. Alternatively you configure the variables via the
7
`settings.cfg` or via environment variables.
8
9
*Please note:* What is set in the config file `settings.cfg` will be overwritten first
10
by the environment variables if they are set and second by the settings configured
11
via the settings interface, which are stored in the database. In brief: `Settings Interface > Environment Variables > settings.cfg`.
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
12
40563c Ivan Novohatski 2026-02-03 12:09:51
added missing vars, updated structure
13
### Application Preferences
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
14
40563c Ivan Novohatski 2026-02-03 12:09:51
added missing vars, updated structure
15
| Variable | Example | Description |
16
|--------------------|-----------------|----------------------------------------------|
17
| `SITE_NAME` | `'Otterwiki'` | The `SITE_NAME` displayed on every page and email |
18
| `SITE_LOGO` | `'/Home/a/logo.png'` | Customize navbar logo url (can be a page attachment) |
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
19
| `SITE_DESCRIPTION` | `'A minimalistic wiki powered by python, markdown and git.'` | The default description used in `<meta>` tags |
40563c Ivan Novohatski 2026-02-03 12:09:51
added missing vars, updated structure
20
| `SITE_ICON` | `'/Home/a/favicon-32x32.png'` | Configure via an url to the image that is displayed as favicon (tab icon, URL icon, bookmark icon). This can be an attachment |
21
| `SITE_LANG` | `'en'` | Configures the lang attribute of the `<html>` lang used in the wiki |
22
| `ROBOTS_TXT` | `'allow'` | Configures how the wiki indicates to visiting robots whether they are allowed to crawl the content, could be `allow` or `disallow` |
23
| `HOME_PAGE` | `'My/Page'` | Configures which page is displayed when visiting the root URL (`/`), leave empty for default (`Home`) or define any page path, including special pages that start with `/-/` |
24
| `HIDE_LOGO` | `False` | Hides or shows An Otter Wiki logo in the sidebar |
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
25
26
### Permission configuration
27
28
| Variable | Example | Description |
29
|------------------|-----------------|----------------------------------------------|
30
| `READ_ACCESS` | `'ANONYMOUS'` | Read access to wiki pages and attachments |
31
| `WRITE_ACCESS` | `'REGISTERED'` | Write access to wiki pages |
32
| `ATTACHMENT_ACCESS` | `'APPROVED'` | Write acccess to attachments |
f02b8f Ralph Thesen 2024-03-23 17:44:24
Updated configuration: added DISABLE_REGISTRATION, SIDEBAR_MENUTREE_*, AUTH_METHOD, COMMIT_MESSAGE, RETAIN_PAGE_NAME_CASE, GIT_WEB_SERVER
33
| `DISABLE_REGISTRATION` | `False` | With `DISABLE_REGISTRATION=True` new users can not sign-up for a new account |
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
34
| `AUTO_APPROVAL` | `False` | With `AUTO_APPROVAL=True` users are approved on registration |
35
| `EMAIL_NEEDS_CONFIRMATION` | `True` | With `EMAIL_NEEDS_CONFIRMATION=True` users have to confirm their email address |
36
| `NOTIFY_ADMINS_ON_REGISTER` | `True` | Notify admins if a new user is registered |
37
38
There are four types of users in the Otterwiki: `ANONYMOUS` are non logged in users.
39
Users that registered via email and are logged in are `REGISTERED`, users approved via
40
the settings menu by an admin are `APPROVED`. In addition to the `APPROVED` flag the `ADMIN`
41
flag can be set. Users with the `ADMIN` flag can edit (and approve) other users. The first registered user is flagged as admin.
42
f02b8f Ralph Thesen 2024-03-23 17:44:24
Updated configuration: added DISABLE_REGISTRATION, SIDEBAR_MENUTREE_*, AUTH_METHOD, COMMIT_MESSAGE, RETAIN_PAGE_NAME_CASE, GIT_WEB_SERVER
43
44
### Sidebar Preferences
45
46
| Variable | Example | Description |
47
| ----------------------- | ---------- | -------------- |
48
| `SIDEBAR_MENUTREE_MODE` | `'SORTED'` | Mode of the sidebar, see below. |
49
| `SIDEBAR_MENUTREE_MAXDEPTH` | `unlimited` | Limit the depth of the pages displayed by any number. |
50
51
For `SIDEBAR_MENUTREE_MODE` pick one of
52
53
- `NONE` (or empty) no sidebar displayed
54
- `SORTED` Directories and pages, sorted
55
- `DIRECTORIES_GROUPED` Directories and pages, with directories grouped first
56
- `DIRECTORIES_ONLY`List directories only.
57
58
### Content and Editing Preferences
59
60
| Variable | Example | Description |
61
| ----------------------- | ---------- | -------------- |
40563c Ivan Novohatski 2026-02-03 12:09:51
added missing vars, updated structure
62
| `COMMIT_MESSAGE` | `'REQUIRED'` | Set to `'OPTIONAL'` if commit messages should be optional |
63
| `RETAIN_PAGE_NAME_CASE` | `False` | Set to `True` to retain case of the page name in the filename used for storing the page |
64
| `TREAT_UNDERSCORE_AS_SPACE_FOR_TITLES` | `False` | Set to `True` to replace underscores (`_`) with spaces in page titles, breadcrumbs, and page index |
65
| `WIKILINK_STYLE` | `'LINKTITLE'` | Set to `'LINKTITLE'` for `[[WikiPage|Text to display]]` format, leave empty for `[[Text to display|WikiPage]]` format (default) |
0d1f0f Ralph Thesen 2025-03-07 22:51:28
fixed typo
66
| `MAX_FORM_MEMORY_SIZE` | `1000000` | The the maximum size of a submitted form, see the [Flask documentation](https://flask.palletsprojects.com/en/stable/config/#MAX_FORM_MEMORY_SIZE). Increase this if you have really large pages to edit and save. |
f02b8f Ralph Thesen 2024-03-23 17:44:24
Updated configuration: added DISABLE_REGISTRATION, SIDEBAR_MENUTREE_*, AUTH_METHOD, COMMIT_MESSAGE, RETAIN_PAGE_NAME_CASE, GIT_WEB_SERVER
67
40563c Ivan Novohatski 2026-02-03 12:09:51
added missing vars, updated structure
68
### Repository Management
69
70
| Variable | Example | Description |
71
| ---------------- | ---------- | -------------- |
72
| `GIT_WEB_SERVER` | `False` | Set to to `True` to allow cloning the wiki via git+http(s) |
73
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
74
### Mail configuration
75
beb69b Ralph Thesen 2026-01-28 22:08:09
updated link to Flask-Mail
76
An Otter Wiki is using [Flask-Mail](https://flask-mail.readthedocs.io/en/latest/).
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
77
78
| Variable | Example | Description |
79
|------------------|-----------------|----------------------------------------------|
80
| `MAIL_DEFAULT_SENDER` | `'otterwiki@example.com'` | The sender address of all mails |
81
| `MAIL_SERVER` | `'smtp.googlemail.com'` | The smtp server address |
82
| `MAIL_PORT` | `465` | The smtp server port |
83
| `MAIL_USERNAME` | `'USERNAME'` | Username for the mail account |
84
| `MAIL_PASSWORD` | `'PASSWORD'` | Password for the mail account |
85
| `MAIL_USE_TLS` | `False` | Use TLS encrytion |
86
| `MAIL_USE_SSL` | `True` | Use SSL encryption |
87
f02b8f Ralph Thesen 2024-03-23 17:44:24
Updated configuration: added DISABLE_REGISTRATION, SIDEBAR_MENUTREE_*, AUTH_METHOD, COMMIT_MESSAGE, RETAIN_PAGE_NAME_CASE, GIT_WEB_SERVER
88
### Authentication configuration
89
90
| Variable | Example | Description |
91
|------------------|-----------------|----------------------------------------------|
92
| `AUTH_METHOD` | `'SIMPLE'` | See below. |
93
94
Per default an Otter Wiki uses a local database for storing authentication information.
95
96
#### Authentication with `PROXY_HEADER`s
97
98
With `AUTH_METHOD='PROXY_HEADER'` an Otter Wiki expects the headers
99
100
- `x-otterwiki-name`
101
- `x-otterwiki-email`
102
- `x-otterwiki-permissions`
103
104
to be set by the proxy service using forward authentication.
105
106
The headers `x-otterwiki-name`and `x-otterwiki-email` are used for receiving author information and `x-otterwiki-permissions` a comma seperated list of permissions `READ`, `WRITE`, `UPLOAD` and `ADMIN`.
107
108
A simplified proof of concept can be found on github: [otterwiki/docs/auth_examples/header-auth](https://github.com/redimp/otterwiki/tree/main/docs/auth_examples/header-auth).
109
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
110
### Advanced configuration
111
112
This applies only when you create the `settings.cfg` manually. Create your
113
`settings.cfg` based upon the `settings.cfg.skeleton` and set the
114
variables fitting to your environment.
115
116
| Variable | Example | Description |
117
|------------------|-----------------|----------------------------------------------|
118
| `SECRET_KEY` | `'CHANGE ME'` | Choose a random string that is used to encrypt user session data |
119
| `REPOSITORY` | `'/path/to/the/repository/root'` | The absolute path to the repository storing the wiki pages |
120
| `SQLALCHEMY_DATABASE_URI` | `'sqlite:////path/to/the/sqlite/file'` | The absolute path to the database storing the user credentials |
b1f52e Ralph Thesen 2025-06-04 21:10:11
added LOG_LEVEL
121
| `LOG_LEVEL`. | `'DEBUG'` | Set the log level to one of `'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`. |
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
122
123
For the `SQLALCHEMY_DATABASE_URI` see <https://flask-sqlalchemy.palletsprojects.com/en/2.x/config/#connection-uri-format>.
124
421730 Ralph Thesen 2025-06-26 08:48:51
How to configure the user/UID running the docker process
125
#### User UID running docker process
126
127
Per default in both the default and the `-slim` image the process running An Otter Wiki (and accessing the files in repository) is running with `uid=33`.
128
129
##### UID in the default image
130
131
To change this when using the default image, please configure the environment variables `PUID` and `PGID`. For example to run as user with `uid=1000 gid=1000` use this `compose.yaml`:
132
133
```yaml
134
services:
135
otterwiki:
136
image: redimp/otterwiki:2
137
restart: unless-stopped
be1525 valankar 2025-08-06 08:32:11
Update configuration.md When using env, I get: validating /home/valankar/otterwiki/docker-compose.yaml: services.otterwiki additional properties 'env' not allowed Change to environment.
138
environment:
421730 Ralph Thesen 2025-06-26 08:48:51
How to configure the user/UID running the docker process
139
PUID: 1000
905b1a valankar 2025-08-06 08:39:35
Update configuration.md Update correct environment variable for GID.
140
PGID: 1000
421730 Ralph Thesen 2025-06-26 08:48:51
How to configure the user/UID running the docker process
141
ports:
142
- 8080:80
143
volumes:
144
- ./app-data:/app-data
145
```
146
147
##### USER in the `-slim` image
148
149
The `-slim` image is running as unpriviliged user must therefore be configured differently: In the way docker intended, with configuring the [user](https://docs.docker.com/reference/compose-file/services/#user). For example to run as user with `uid=1000 gid=1000` use this `compose.yaml`:
150
151
```yaml
152
services:
153
otterwiki:
154
image: redimp/otterwiki:2-slim
155
restart: unless-stopped
156
user: 1000:1000
157
ports:
158
- 8080:8080
159
volumes:
160
- ./app-data:/app-data
161
```
162
163
Make sure that the configured `uid:gid` has read- and write permissions to volume mounted as `/app-data`.
164
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
165
### Reverse Proxy and IPs
166
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
167
Running the docker container behind a reverse proxy will show only the IP of the reverse proxy in the log files. With setting `REAL_IP_FROM` to the ip address or network of the reverse proxy, the IPs of the connection clients will be logged.
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
168
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
169
| Variable | Example | Description |
170
|------------------|-------------------|----------------------------------------------|
171
| `REAL_IP_FROM` | `'172.20.0.0/24'` | Configure wiki to respect `X-Real-IP` header in the requests coming from this IP or network. |