Home A - Z
Menu

An Otter Wiki

Blame

f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
1 
# Installation
2
bb20b4 Ralph Thesen 2024-05-05 09:06:07
fixed link
3
The recommend way of running An Otter Wiki is via [[docker compose|Installation#using-docker-compose]]. For deploying in kubernetes via [[Helm|Installation#kubernetes]].
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
4
5
## Requirements
6
7
The **CPU** requirements are pretty low, you can run it on a Raspberry Pi 1 A (ARMv6). The **RAM** required is around 100MiB (according to `docker stats`). The required disk **storage** depends on the content, please keep in mind, that the backend is a git repository that never forgets: Deleting a page or an attachment does not free up any space. The wiki needs no internet access. Clients using the wiki need only access to the server running the wiki, so it can run in an environment which is _isolated_ from the internet.
8
6878e0 Ralph Thesen 2025-03-07 00:18:44
fixed typo
9
As URL a dedicated domain (e.g. `wiki.domain.tld`) is required, the wiki can not be mapped into a subfolder.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
10
f7923b Ralph Thesen 2023-12-06 16:58:57
Update requirements: Clients need javascript
11
Client requirement: Javascript must be activated in your browser to use the wiki.
12
ab255a Ralph Thesen 2023-11-26 13:35:43
Updated docker cli command
13
## Using docker cli
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
14
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
15
An Otter Wiki is published as a Docker image on Docker hub as [`redimp/otterwiki`](https://hub.docker.com/r/redimp/otterwiki). The stable images are build for the plattforms `amd64`, `arm64`, `armv7` and `armv6`.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
16
17
Make sure you have [docker](https://docs.docker.com/engine/install/) installed.
18
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
19
To run an otter wiki via docker cli, listening on port 8080 and using a local directory for data persistence, use the following command:
ab255a Ralph Thesen 2023-11-26 13:35:43
Updated docker cli command
20
```bash
21
docker run --name otterwiki \
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
22
-p 8080:80 \
ab255a Ralph Thesen 2023-11-26 13:35:43
Updated docker cli command
23
-v $PWD/app-data:/app-data \
14546e Ralph Thesen 2024-01-03 11:15:44
use image tag :2 instead of :2.0
24
redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
25
```
26
Open the wiki via http://127.0.0.1:8080 if you are running the docker command on your machine.
27
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
28
You can configure the application with environment variables e.g.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
29
```
30
-e SITE_NAME="My Wiki" -e SITE_DESCRIPTION="An otter wiki run via docker"
31
```
32
For all configuration options please see [[Configuration]].
33
34
## Using docker compose
35
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
36
The recommended way of running An Otter Wiki is via `docker compose`.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
37
38
1. Create a `docker-compose.yaml` file
39
40
```yaml
41
services:
42
otterwiki:
14546e Ralph Thesen 2024-01-03 11:15:44
use image tag :2 instead of :2.0
43
image: redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
44
restart: unless-stopped
45
ports:
46
- 8080:80
47
volumes:
48
- ./app-data:/app-data
49
```
50
51
2. Run `docker compose up -d`
52
3. Access the wiki via http://127.0.0.1:8080 if run on your machine.
53
4. Register your account. The first account is an admin-account with access to the application settings. The first accounts email address doesn't need to be confirmed nor has the account to be activated.
54
5. Customize the settings to your liking.
55
6. It's highly recommended to use a webserver as reverse proxy to connect to the docker process, see [Reverse Proxy](#reverse-proxy) below.
56
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
57
Alternatively you can configure the application using environment variables, for example:
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
58
59
```yaml
60
services:
61
otterwiki:
14546e Ralph Thesen 2024-01-03 11:15:44
use image tag :2 instead of :2.0
62
image: redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
63
restart: unless-stopped
64
ports:
65
- 8080:80
66
volumes:
67
- ./app-data:/app-data
334777 Ralph Thesen 2024-10-30 23:19:20
fixed typo
68
environment:
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
69
MAIL_DEFAULT_SENDER: no-reply@example.com
70
MAIL_SERVER: smtp.server.tld
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
71
MAIL_PORT: 465
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
72
MAIL_USERNAME: otterwiki@example.com
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
73
MAIL_PASSWORD: somepassword
74
MAIL_USE_SSL: True
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
75
```
76
77
For all configuration options please see [[Configuration]].
78
79
## podman and podman-compose
80
81
An Otter Wiki can be run with `podman` and `podman-compose` in the same way as with` docker` and `docker compose` please see above.
82
92d0d9 Ralph Thesen 2024-10-19 16:04:09
Added IMPORTANT block linking to the FAQ with SELinux environments
83
> [!IMPORTANT]
84
> If you are running podman in an SELinux environment, please check the
85
> [[FAQ|FAQ#environments-with-selinux]] section about environments with SELinux.
86
21867d Ralph Thesen 2024-10-19 17:56:40
Added information about how to run the -slim image variant.
87
## The `-slim` image variant
88
17bbb0 Ralph Thesen 2025-11-09 16:05:13
Tip about using the full image to initialize and switching to the slim image.
89
The full image of An Otter Wiki runs as root user (with uid=0) and comes bundled with nginx that listens on port 80. The lighter image variant is the `-slim` image: It's based on alpine, has no nginx bundled and an uWSGI server is running as unprivileged `www-data` user (with uid=33). uWSGI serves both An Otter Wiki and the static files and listens on port 8080.
21867d Ralph Thesen 2024-10-19 17:56:40
Added information about how to run the -slim image variant.
90
91
Except for the exposes port, the images are interchangeable. For example a `docker-compose.yaml` running the most recent version of a `-slim` image:
92
93
```yaml
94
services:
95
otterwiki:
96
image: redimp/otterwiki:2-slim
97
restart: unless-stopped
98
ports:
99
- 8080:8080
100
volumes:
101
- ./app-data:/app-data
102
```
103
17bbb0 Ralph Thesen 2025-11-09 16:05:13
Tip about using the full image to initialize and switching to the slim image.
104
The `redimp/otterwiki:2-slim` image is as stable as the full image, after all it is what is running [otterwiki.com](https://otterwiki.com).
105
106
> [!TIP]
107
> To ensure your application data directory is accessible when using the `-slim` image, make sure user ID 33 and group ID 33 have appropriate permissions. You can use the full image to initially set up this directory, then switch to the `-slim` variant.
21867d Ralph Thesen 2024-10-19 17:56:40
Added information about how to run the -slim image variant.
108
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
109
## Kubernetes
110
111
An Otter Wiki can be conveniently deployed on kubernetes using the official Helm Chart.
e977a2 Ralph Thesen 2024-12-20 12:31:13
Updated helm chart location
112
```bash
113
# add the helm chart repository
114
helm repo add otterwiki https://charts.otterwiki.com
115
# update the repository
116
helm repo update otterwiki
117
```
118
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
119
For example you can create a new deployment with an ingress on `otterwiki.example.com` with
120
121
```bash
122
helm install otterwiki-example \
56a04d Ralph Thesen 2025-08-14 21:22:35
Updated Helm Chart Version
123
--set config.SITE_NAME="My Otter Wiki" \
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
124
--set config.SITE_DESCRIPTION="An Otter Wiki deployed with Helm" \
125
--set ingress.enabled=true \
126
--set ingress.hosts[0].host="otterwiki.example.com" \
56a04d Ralph Thesen 2025-08-14 21:22:35
Updated Helm Chart Version
127
--version 0.1.1 \
e977a2 Ralph Thesen 2024-12-20 12:31:13
Updated helm chart location
128
otterwiki/otterwiki
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
129
```
130
131
Please refer to the [chart](https://github.com/redimp/otterwiki/tree/main/helm) for
132
a detailed README with instructions, more examples and informations about the default values
133
of the chart.
134
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
135
## From source as WSGI application with uwsgi
136
137
1. Install the prerequisites
138
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
139
i. Debian / Ubuntu
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
140
```
141
apt install git build-essential python3-dev python3-venv
142
```
143
ii. RHEL8 / Fedora / CentOS8 / Rocky Linux 8
144
```
145
yum install make python3-devel
146
```
147
2. Clone the otterwiki repository and enter the directory
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
148
```
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
149
git clone https://github.com/redimp/otterwiki.git
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
150
cd otterwiki
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
151
```
152
3. Create and initialize the repository where the otterwiki data lives
153
```bash
154
mkdir -p app-data/repository
155
# initialize the empty repository
ec48ab Ralph Thesen 2024-10-27 12:11:25
Fixed the systemd example
156
git init -b main app-data/repository
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
157
```
158
4. Create a minimal `settings.cfg` e.g. via
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
159
```bash
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
160
echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
161
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
c9375d Ralph Thesen 2026-01-02 16:10:43
fixed python command
162
echo "SECRET_KEY='$(python3 -c 'import secrets; print(secrets.token_hex())')'" >> settings.cfg
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
163
```
164
5. Create a virtual environment and install An Otter Wiki
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
165
```
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
166
python3 -m venv venv
167
./venv/bin/pip install -U pip uwsgi
168
./venv/bin/pip install .
169
```
170
6. Run uwsgi listening on the localhost port 8080
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
171
```bash
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
172
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
cb8dde Ralph Thesen 2024-08-30 11:15:17
Fixed typos, spotted by https://github.com/KlingelDev
173
./venv/bin/uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
174
```
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
175
7. Open <http://127.0.0.1:8080> in your browser.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
176
8. Register your account. The first account is an admin-account with access to the application settings.
177
9. Alternatively can you configure the application using the `settings.cfg`. For all configuration options please see [[Configuration]].
178
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
179
180
```systemd
181
[Unit]
182
Description=uWSGI server for An Otter Wiki
183
184
[Service]
185
User=www-data
186
Group=www-data
ec48ab Ralph Thesen 2024-10-27 12:11:25
Fixed the systemd example
187
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
cb8dde Ralph Thesen 2024-08-30 11:15:17
Fixed typos, spotted by https://github.com/KlingelDev
188
ExecStart=/path/to/an/otterwiki/env/bin/uwsgi --http 127.0.0.1:8080 --enable-threads --die-on-term -w otterwiki.server:app
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
189
SyslogIdentifier=otterwiki
190
191
[Install]
192
WantedBy=multi-user.target
193
```
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
194
195
Make sure to adapt the `/path/to` and that the configured user can read and write the database and the repository folder.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
196
ec48ab Ralph Thesen 2024-10-27 12:11:25
Fixed the systemd example
197
11. Run `systemctl daemon-reload` and `systemctl start otterwiki.service`, check `systemctl status otterwiki.service` for errors.
198
199
> [!NOTE]
200
> It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see [Reverse Proxy](#reverse-proxy) below.
201
202
If you want to skip the reverse proxy consider to bind uwsgi not to just the local ip `127.0.0.1`, but to all ips of the host running An Otter Wiki with `--http 0.0.0.0:8080`.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
203
204
# Reverse Proxy
205
206
A reverse proxy is a server that sits in front of web servers and forwards
207
client (e.g. web browser) requests to those web servers. They are useful
208
when hosting multiple services on a host and make it much easier to configure
209
https. Neither An Otter Wiki itself nor the in the docker image provides https.
210
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
211
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For
212
more detailed informations please check the corresponding software documentation.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
213
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
214
Also check out [[Configuration]] for additional info on passing real IPs to the wiki.
215
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
216
## NGINX
217
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
218
This is a minimal example of a config that configures NGINX as a reverse proxy.
219
The full documentation about NGINX as reverse proxy can be found [here](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
220
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
221
It's assumed that An Otter Wiki is running either in a docker container or as a `uwsgi` process and listening on port 8080.
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
222
223
```nginx
224
server {
225
server_name wiki.domain.tld;
226
listen 80;
227
location / {
291014 Ralph Thesen 2024-06-08 23:49:27
Bump up the client_max_body_size up to 64MB to allow using attachments.
228
proxy_set_header Host $http_host;
229
proxy_set_header X-Real-IP $remote_addr;
230
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
231
proxy_set_header X-Forwarded-Host $http_host;
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
232
proxy_set_header X-Forwarded-Proto $scheme;
291014 Ralph Thesen 2024-06-08 23:49:27
Bump up the client_max_body_size up to 64MB to allow using attachments.
233
proxy_pass http://127.0.0.1:8080;
234
client_max_body_size 64M; # for attachments of a size up to 64 Mb
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
235
}
236
}
237
```
238
239
### NGINX on Debian, Ubuntu and derivates
240
241
- Install nginx via `apt install -y nginx`
242
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
243
- Check the syntax via `nginx -t`
244
- Restart nginx via `systemctl restart nginx`
245
- Open <http://wiki.domain.tld> in your browser
246
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
247
248
### NGINX on RHEL, CentOS, Rocky and derivates
249
250
- Install nginx via `dnf install nginx`
251
- Start NGINX and enable at boot: `sudo systemctl enable --now nginx`
252
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
253
- Create the `otterwiki.conf` in `/etc/nginx/conf.d/`
254
- Check the syntax via `nginx -t`
255
- Restart nginx via `systemctl restart nginx`
256
- Open <http://wiki.domain.tld> in your browser
257
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
258
259
See <https://www.redhat.com/sysadmin/setting-reverse-proxies-nginx> for a complete guide.
260
261
## Apache
262
263
This is a minimal example how to configure Apache as reverse proxy. Please see the [Apache documentation](https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html) for complete details.
264
265
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
266
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
267
```apache
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
268
<VirtualHost *:*>
269
ServerName wiki.domain.tld
270
ProxyPreserveHost On
271
ProxyPass / http://0.0.0.0:8080/
272
ProxyPassReverse / http://0.0.0.0:8080/
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
273
ProxyAddHeaders On
274
RequestHeader set X-Forwarded-Proto "http"
275
RequestHeader set X-Real-IP %{REMOTE_ADDR}e
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
276
</VirtualHost>
277
```
278
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
279
If you're using HTTPS, change `X-Forwarded-Proto "http"` to `X-Forwarded-Proto "https"` and `RequestHeader set X-Real-IP %{REMOTE_ADDR}e` to `RequestHeader set X-Real-IP %{REMOTE_ADDR}s`.
280
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
281
### Apache on Debian, Ubuntu and derivates
282
283
- Install apache2 via `apt install -y apache2`
284
- Enable proxy modules via `a2enmod proxy proxy_http`
285
- Create the `otterwiki.conf` config file in `/etc/apache2/site-available/`
286
- Enable the site via `a2ensite otterwiki`
287
- Restart apache2 `systemctl restart apache2`
288
- Open <http://wiki.domain.tld> in your browser
289
- Check `journalctl -xeu apache2.service` and `/var/log/apache2/error.log` for error messages.
290
291
### Apache on RHEL, CentOS, Rocky and derivates
292
293
- Install apache2 via `dnf install httpd`
679b7f Ralph Thesen 2024-05-05 09:04:15
added: helm chart example and link. fixed: Typos, tabs, trailing whitespaces.
294
- Start apache2 and enable at boot: `sudo systemctl enable --now httpd`
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
295
- Create the `otterwiki.conf` config file in `/etc/httpd/conf.d/`
296
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
297
- Restart apache2 via `systemctl restart httpd`
298
- Open <http://wiki.domain.tld> in your browser
299
- Check `journalctl -xeu httpd.service` and `/var/log/httpd/error_log` for error messages.
300
301
## Caddy
302
303
[Caddy](https://caddyserver.com/) is an open source webserver with a very light configuration that makes a fine reverse proxy.
304
305
After [installing](https://caddyserver.com/docs/install) caddy, configure `/etc/caddy/Caddyfile` with e.g.
306
307
```
308
domain.tld {
33bd57 deseven 2025-12-23 16:17:54
added headers to all reverse proxy configs, updated configuration section
309
reverse_proxy localhost:8080 {
310
header_up Host {http.request.host}
311
header_up X-Forwarded-Proto {scheme}
312
header_up X-Real-IP {remote_host}
313
}
f1509e Ralph Thesen 2023-11-18 14:39:06
Added documentation for installing An Otter Wiki
314
}
315
```
316
9fae76 Otterwiki Robot 2025-07-20 15:06:40
fixed typos and some polishing
317
With a server accessible from the internet, `domain.tld` being a proper domain name with A/AAAA DNS records pointing to the server, caddy will [automatically](https://caddyserver.com/docs/automatic-https) serve HTTPS.