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