Blame
34401d | Ralph Thesen | 2023-11-18 14:40:43 | 1 | # Configuration |
2 | ||||
4c6b41 | Ralph Thesen | 2023-12-04 13:05:43 | 3 | The [[Installation Guide|Installation]] can be found [[here|Installation]]. |
4 | ||||
34401d | Ralph Thesen | 2023-11-18 14:40:43 | 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 | 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 | 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 | 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 | 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 | 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) | | |||
62 | ||||
34401d | Ralph Thesen | 2023-11-18 14:40:43 | 63 | ### Mail configuration |
64 | ||||
f02b8f | Ralph Thesen | 2024-03-23 17:44:24 | 65 | An Otter Wiki is using [Flask-Mail](https://pythonhosted.org/Flask-Mail/). |
34401d | Ralph Thesen | 2023-11-18 14:40:43 | 66 | |
67 | | Variable | Example | Description | | |||
68 | |------------------|-----------------|----------------------------------------------| | |||
69 | | `MAIL_DEFAULT_SENDER` | `'otterwiki@example.com'` | The sender address of all mails | | |||
70 | | `MAIL_SERVER` | `'smtp.googlemail.com'` | The smtp server address | | |||
71 | | `MAIL_PORT` | `465` | The smtp server port | | |||
72 | | `MAIL_USERNAME` | `'USERNAME'` | Username for the mail account | | |||
73 | | `MAIL_PASSWORD` | `'PASSWORD'` | Password for the mail account | | |||
74 | | `MAIL_USE_TLS` | `False` | Use TLS encrytion | | |||
75 | | `MAIL_USE_SSL` | `True` | Use SSL encryption | | |||
76 | ||||
f02b8f | Ralph Thesen | 2024-03-23 17:44:24 | 77 | ### Authentication configuration |
78 | ||||
79 | | Variable | Example | Description | | |||
80 | |------------------|-----------------|----------------------------------------------| | |||
81 | | `AUTH_METHOD` | `'SIMPLE'` | See below. | | |||
82 | ||||
83 | Per default an Otter Wiki uses a local database for storing authentication information. | |||
84 | ||||
85 | #### Authentication with `PROXY_HEADER`s | |||
86 | ||||
87 | With `AUTH_METHOD='PROXY_HEADER'` an Otter Wiki expects the headers | |||
88 | ||||
89 | - `x-otterwiki-name` | |||
90 | - `x-otterwiki-email` | |||
91 | - `x-otterwiki-permissions` | |||
92 | ||||
93 | to be set by the proxy service using forward authentication. | |||
94 | ||||
95 | 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`. | |||
96 | ||||
97 | 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). | |||
98 | ||||
34401d | Ralph Thesen | 2023-11-18 14:40:43 | 99 | ### Advanced configuration |
100 | ||||
101 | This applies only when you create the `settings.cfg` manually. Create your | |||
102 | `settings.cfg` based upon the `settings.cfg.skeleton` and set the | |||
103 | variables fitting to your environment. | |||
104 | ||||
105 | | Variable | Example | Description | | |||
106 | |------------------|-----------------|----------------------------------------------| | |||
107 | | `SECRET_KEY` | `'CHANGE ME'` | Choose a random string that is used to encrypt user session data | | |||
108 | | `REPOSITORY` | `'/path/to/the/repository/root'` | The absolute path to the repository storing the wiki pages | | |||
109 | | `SQLALCHEMY_DATABASE_URI` | `'sqlite:////path/to/the/sqlite/file'` | The absolute path to the database storing the user credentials | | |||
110 | ||||
111 | For the `SQLALCHEMY_DATABASE_URI` see <https://flask-sqlalchemy.palletsprojects.com/en/2.x/config/#connection-uri-format>. | |||
112 | ||||
113 | ### Reverse Proxy and IPs | |||
114 | ||||
115 | 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. | |||
116 | ||||
117 | | Variable | Example | Description | | |||
118 | |------------------|------------------|----------------------------------------------| | |||
119 | | `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> | |