Configuration - blame None

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) \|
0d1f0f	Ralph Thesen	2025-03-07 22:51:28	62	\| `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	63
34401d	Ralph Thesen	2023-11-18 14:40:43	64	### Mail configuration
			65
f02b8f	Ralph Thesen	2024-03-23 17:44:24	66	An Otter Wiki is using [Flask-Mail](https://pythonhosted.org/Flask-Mail/).
34401d	Ralph Thesen	2023-11-18 14:40:43	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	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	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 \|
b1f52e	Ralph Thesen	2025-06-04 21:10:11	111	\| `LOG_LEVEL`. \| `'DEBUG'` \| Set the log level to one of `'DEBUG'`, `'INFO'`, `'WARNING'`, `'ERROR'`. \|
34401d	Ralph Thesen	2023-11-18 14:40:43	112
			113	For the `SQLALCHEMY_DATABASE_URI` see <https://flask-sqlalchemy.palletsprojects.com/en/2.x/config/#connection-uri-format>.
			114
421730	Ralph Thesen	2025-06-26 08:48:51	115	#### User UID running docker process
			116
			117	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`.
			118
			119	##### UID in the default image
			120
			121	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`:
			122
			123	```yaml
			124	services:
			125	otterwiki:
			126	image: redimp/otterwiki:2
			127	restart: unless-stopped
be1525	valankar	2025-08-06 08:32:11	128	environment:
421730	Ralph Thesen	2025-06-26 08:48:51	129	PUID: 1000
905b1a	valankar	2025-08-06 08:39:35	130	PGID: 1000
421730	Ralph Thesen	2025-06-26 08:48:51	131	ports:
			132	- 8080:80
			133	volumes:
			134	- ./app-data:/app-data
			135	```
			136
			137	##### USER in the `-slim` image
			138
			139	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`:
			140
			141	```yaml
			142	services:
			143	otterwiki:
			144	image: redimp/otterwiki:2-slim
			145	restart: unless-stopped
			146	user: 1000:1000
			147	ports:
			148	- 8080:8080
			149	volumes:
			150	- ./app-data:/app-data
			151	```
			152
			153	Make sure that the configured `uid:gid` has read- and write permissions to volume mounted as `/app-data`.
			154
34401d	Ralph Thesen	2023-11-18 14:40:43	155	### Reverse Proxy and IPs
			156
			157	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.
			158
			159	\| Variable \| Example \| Description \|
			160	\|------------------\|------------------\|----------------------------------------------\|
			161	\| `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> \|