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
13
### Branding
14
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) |
19
| `SITE_DESCRIPTION` | `'A minimalistic wiki powered by python, markdown and git.'` | The default description used in `<meta>` tags |
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
22
23
### Permission configuration
24
25
| Variable | Example | Description |
26
|------------------|-----------------|----------------------------------------------|
27
| `READ_ACCESS` | `'ANONYMOUS'` | Read access to wiki pages and attachments |
28
| `WRITE_ACCESS` | `'REGISTERED'` | Write access to wiki pages |
29
| `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
30
| `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
31
| `AUTO_APPROVAL` | `False` | With `AUTO_APPROVAL=True` users are approved on registration |
32
| `EMAIL_NEEDS_CONFIRMATION` | `True` | With `EMAIL_NEEDS_CONFIRMATION=True` users have to confirm their email address |
33
| `NOTIFY_ADMINS_ON_REGISTER` | `True` | Notify admins if a new user is registered |
34
35
There are four types of users in the Otterwiki: `ANONYMOUS` are non logged in users.
36
Users that registered via email and are logged in are `REGISTERED`, users approved via
37
the settings menu by an admin are `APPROVED`. In addition to the `APPROVED` flag the `ADMIN`
38
flag can be set. Users with the `ADMIN` flag can edit (and approve) other users. The first registered user is flagged as admin.
39
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
40
41
### Sidebar Preferences
42
43
| Variable | Example | Description |
44
| ----------------------- | ---------- | -------------- |
45
| `SIDEBAR_MENUTREE_MODE` | `'SORTED'` | Mode of the sidebar, see below. |
46
| `SIDEBAR_MENUTREE_MAXDEPTH` | `unlimited` | Limit the depth of the pages displayed by any number. |
47
48
For `SIDEBAR_MENUTREE_MODE` pick one of
49
50
- `NONE` (or empty) no sidebar displayed
51
- `SORTED` Directories and pages, sorted
52
- `DIRECTORIES_GROUPED` Directories and pages, with directories grouped first
53
- `DIRECTORIES_ONLY`List directories only.
54
55
### Content and Editing Preferences
56
57
| Variable | Example | Description |
58
| ----------------------- | ---------- | -------------- |
59
| `COMMIT_MESSAGE` | `'REQUIRED'` | set `COMMIT_MESSAGE='OPTIONAL'` if commit messages are optional |
60
| `RETAIN_PAGE_NAME_CASE` | `False` | set `RETAIN_PAGE_NAME_CASE=True` to
61
| `GIT_WEB_SERVER` | `False` | Set to to true to allow cloning the wiki via git+http(s) |
93404a Ralph Thesen 2025-03-07 22:34:29
added MAX_FORM_MEMORY_SIZE
62
| `MAX_FORM_MEMORY_SIZE` | `500000` | 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
63
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
64
### Mail configuration
65
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
66
An Otter Wiki is using [Flask-Mail](https://pythonhosted.org/Flask-Mail/).
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
67
68
| Variable | Example | Description |
69
|------------------|-----------------|----------------------------------------------|
70
| `MAIL_DEFAULT_SENDER` | `'otterwiki@example.com'` | The sender address of all mails |
71
| `MAIL_SERVER` | `'smtp.googlemail.com'` | The smtp server address |
72
| `MAIL_PORT` | `465` | The smtp server port |
73
| `MAIL_USERNAME` | `'USERNAME'` | Username for the mail account |
74
| `MAIL_PASSWORD` | `'PASSWORD'` | Password for the mail account |
75
| `MAIL_USE_TLS` | `False` | Use TLS encrytion |
76
| `MAIL_USE_SSL` | `True` | Use SSL encryption |
77
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
78
### Authentication configuration
79
80
| Variable | Example | Description |
81
|------------------|-----------------|----------------------------------------------|
82
| `AUTH_METHOD` | `'SIMPLE'` | See below. |
83
84
Per default an Otter Wiki uses a local database for storing authentication information.
85
86
#### Authentication with `PROXY_HEADER`s
87
88
With `AUTH_METHOD='PROXY_HEADER'` an Otter Wiki expects the headers
89
90
- `x-otterwiki-name`
91
- `x-otterwiki-email`
92
- `x-otterwiki-permissions`
93
94
to be set by the proxy service using forward authentication.
95
96
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`.
97
98
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).
99
34401d Ralph Thesen 2023-11-18 14:40:43
Added documentation for configuring An Otter Wiki
100
### Advanced configuration
101
102
This applies only when you create the `settings.cfg` manually. Create your
103
`settings.cfg` based upon the `settings.cfg.skeleton` and set the
104
variables fitting to your environment.
105
106
| Variable | Example | Description |
107
|------------------|-----------------|----------------------------------------------|
108
| `SECRET_KEY` | `'CHANGE ME'` | Choose a random string that is used to encrypt user session data |
109
| `REPOSITORY` | `'/path/to/the/repository/root'` | The absolute path to the repository storing the wiki pages |
110
| `SQLALCHEMY_DATABASE_URI` | `'sqlite:////path/to/the/sqlite/file'` | The absolute path to the database storing the user credentials |
111
112
For the `SQLALCHEMY_DATABASE_URI` see <https://flask-sqlalchemy.palletsprojects.com/en/2.x/config/#connection-uri-format>.
113
114
### Reverse Proxy and IPs
115
116
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 of the reverse proxy, the IPs of the connection clients will be logged.
117
118
| Variable | Example | Description |
119
|------------------|------------------|----------------------------------------------|
120
| `REAL_IP_FROM` | `'10.0.0.0/8'` | Configure nginx to respect `real_ip_header`, see <http://nginx.org/en/docs/http/ngx_http_realip_module.html> |