Home A - Z
Menu

An Otter Wiki

Blame

f1509e Ralph Thesen 2023-11-18 14:39:06 1 
# Installation
2
bb20b4 Ralph Thesen 2024-05-05 09:06:07 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 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 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 10
f7923b Ralph Thesen 2023-12-06 16:58:57 11
Client requirement: Javascript must be activated in your browser to use the wiki.
12
ab255a Ralph Thesen 2023-11-26 13:35:43 13
## Using docker cli
f1509e Ralph Thesen 2023-11-18 14:39:06 14
679b7f Ralph Thesen 2024-05-05 09:04:15 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 16
17
Make sure you have [docker](https://docs.docker.com/engine/install/) installed.
18
9fae76 Otterwiki Robot 2025-07-20 15:06:40 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 20
```bash
21
docker run --name otterwiki \
679b7f Ralph Thesen 2024-05-05 09:04:15 22
-p 8080:80 \
ab255a Ralph Thesen 2023-11-26 13:35:43 23
-v $PWD/app-data:/app-data \
14546e Ralph Thesen 2024-01-03 11:15:44 24
redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06 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 28
You can configure the application with environment variables e.g.
f1509e Ralph Thesen 2023-11-18 14:39:06 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 36
The recommended way of running An Otter Wiki is via `docker compose`.
f1509e Ralph Thesen 2023-11-18 14:39:06 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 43
image: redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06 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 57
Alternatively you can configure the application using environment variables, for example:
f1509e Ralph Thesen 2023-11-18 14:39:06 58
59
```yaml
60
services:
61
otterwiki:
14546e Ralph Thesen 2024-01-03 11:15:44 62
image: redimp/otterwiki:2
f1509e Ralph Thesen 2023-11-18 14:39:06 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 68
environment:
f1509e Ralph Thesen 2023-11-18 14:39:06 69
MAIL_DEFAULT_SENDER: no-reply@example.com
70
MAIL_SERVER: smtp.server.tld
679b7f Ralph Thesen 2024-05-05 09:04:15 71
MAIL_PORT: 465
f1509e Ralph Thesen 2023-11-18 14:39:06 72
MAIL_USERNAME: otterwiki@example.com
679b7f Ralph Thesen 2024-05-05 09:04:15 73
MAIL_PASSWORD: somepassword
74
MAIL_USE_SSL: True
f1509e Ralph Thesen 2023-11-18 14:39:06 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 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 87
## The `-slim` image variant
88
89
The 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.
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
104
The `redimp/otterwiki:2-slim` image is as stable as the 'fat' image, after all it is what is running [otterwiki.com](https://otterwiki.com).
105
679b7f Ralph Thesen 2024-05-05 09:04:15 106
## Kubernetes
107
108
An Otter Wiki can be conveniently deployed on kubernetes using the official Helm Chart.
e977a2 Ralph Thesen 2024-12-20 12:31:13 109
```bash
110
# add the helm chart repository
111
helm repo add otterwiki https://charts.otterwiki.com
112
# update the repository
113
helm repo update otterwiki
114
```
115
679b7f Ralph Thesen 2024-05-05 09:04:15 116
For example you can create a new deployment with an ingress on `otterwiki.example.com` with
117
118
```bash
119
helm install otterwiki-example \
56a04d Ralph Thesen 2025-08-14 21:22:35 120
--set config.SITE_NAME="My Otter Wiki" \
679b7f Ralph Thesen 2024-05-05 09:04:15 121
--set config.SITE_DESCRIPTION="An Otter Wiki deployed with Helm" \
122
--set ingress.enabled=true \
123
--set ingress.hosts[0].host="otterwiki.example.com" \
56a04d Ralph Thesen 2025-08-14 21:22:35 124
--version 0.1.1 \
e977a2 Ralph Thesen 2024-12-20 12:31:13 125
otterwiki/otterwiki
679b7f Ralph Thesen 2024-05-05 09:04:15 126
```
127
128
Please refer to the [chart](https://github.com/redimp/otterwiki/tree/main/helm) for
129
a detailed README with instructions, more examples and informations about the default values
130
of the chart.
131
f1509e Ralph Thesen 2023-11-18 14:39:06 132
## From source as WSGI application with uwsgi
133
134
1. Install the prerequisites
135
679b7f Ralph Thesen 2024-05-05 09:04:15 136
i. Debian / Ubuntu
f1509e Ralph Thesen 2023-11-18 14:39:06 137
```
138
apt install git build-essential python3-dev python3-venv
139
```
140
ii. RHEL8 / Fedora / CentOS8 / Rocky Linux 8
141
```
142
yum install make python3-devel
143
```
144
2. Clone the otterwiki repository and enter the directory
679b7f Ralph Thesen 2024-05-05 09:04:15 145
```
f1509e Ralph Thesen 2023-11-18 14:39:06 146
git clone https://github.com/redimp/otterwiki.git
679b7f Ralph Thesen 2024-05-05 09:04:15 147
cd otterwiki
f1509e Ralph Thesen 2023-11-18 14:39:06 148
```
149
3. Create and initialize the repository where the otterwiki data lives
150
```bash
151
mkdir -p app-data/repository
152
# initialize the empty repository
ec48ab Ralph Thesen 2024-10-27 12:11:25 153
git init -b main app-data/repository
f1509e Ralph Thesen 2023-11-18 14:39:06 154
```
155
4. Create a minimal `settings.cfg` e.g. via
679b7f Ralph Thesen 2024-05-05 09:04:15 156
```bash
f1509e Ralph Thesen 2023-11-18 14:39:06 157
echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
679b7f Ralph Thesen 2024-05-05 09:04:15 158
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
ec48ab Ralph Thesen 2024-10-27 12:11:25 159
echo "SECRET_KEY='$(python -c 'import secrets; print(secrets.token_hex())')'" >> settings.cfg
f1509e Ralph Thesen 2023-11-18 14:39:06 160
```
161
5. Create a virtual environment and install An Otter Wiki
679b7f Ralph Thesen 2024-05-05 09:04:15 162
```
f1509e Ralph Thesen 2023-11-18 14:39:06 163
python3 -m venv venv
164
./venv/bin/pip install -U pip uwsgi
165
./venv/bin/pip install .
166
```
167
6. Run uwsgi listening on the localhost port 8080
679b7f Ralph Thesen 2024-05-05 09:04:15 168
```bash
f1509e Ralph Thesen 2023-11-18 14:39:06 169
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
cb8dde Ralph Thesen 2024-08-30 11:15:17 170
./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 171
```
9fae76 Otterwiki Robot 2025-07-20 15:06:40 172
7. Open <http://127.0.0.1:8080> in your browser.
f1509e Ralph Thesen 2023-11-18 14:39:06 173
8. Register your account. The first account is an admin-account with access to the application settings.
174
9. Alternatively can you configure the application using the `settings.cfg`. For all configuration options please see [[Configuration]].
175
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
176
177
```systemd
178
[Unit]
179
Description=uWSGI server for An Otter Wiki
180
181
[Service]
182
User=www-data
183
Group=www-data
ec48ab Ralph Thesen 2024-10-27 12:11:25 184
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
cb8dde Ralph Thesen 2024-08-30 11:15:17 185
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 186
SyslogIdentifier=otterwiki
187
188
[Install]
189
WantedBy=multi-user.target
190
```
9fae76 Otterwiki Robot 2025-07-20 15:06:40 191
192
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 193
ec48ab Ralph Thesen 2024-10-27 12:11:25 194
11. Run `systemctl daemon-reload` and `systemctl start otterwiki.service`, check `systemctl status otterwiki.service` for errors.
195
196
> [!NOTE]
197
> It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see [Reverse Proxy](#reverse-proxy) below.
198
199
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 200
201
# Reverse Proxy
202
203
A reverse proxy is a server that sits in front of web servers and forwards
204
client (e.g. web browser) requests to those web servers. They are useful
205
when hosting multiple services on a host and make it much easier to configure
206
https. Neither An Otter Wiki itself nor the in the docker image provides https.
207
9fae76 Otterwiki Robot 2025-07-20 15:06:40 208
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For
209
more detailed informations please check the corresponding software documentation.
f1509e Ralph Thesen 2023-11-18 14:39:06 210
211
## NGINX
212
9fae76 Otterwiki Robot 2025-07-20 15:06:40 213
This is a minimal example of a config that configures NGINX as a reverse proxy.
214
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 215
9fae76 Otterwiki Robot 2025-07-20 15:06:40 216
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 217
218
```nginx
219
server {
220
server_name wiki.domain.tld;
221
listen 80;
222
location / {
291014 Ralph Thesen 2024-06-08 23:49:27 223
proxy_set_header Host $http_host;
224
proxy_set_header X-Real-IP $remote_addr;
225
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
226
proxy_set_header X-Forwarded-Host $http_host;
227
proxy_pass http://127.0.0.1:8080;
228
client_max_body_size 64M; # for attachments of a size up to 64 Mb
f1509e Ralph Thesen 2023-11-18 14:39:06 229
}
230
}
231
```
232
233
### NGINX on Debian, Ubuntu and derivates
234
235
- Install nginx via `apt install -y nginx`
236
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
237
- Check the syntax via `nginx -t`
238
- Restart nginx via `systemctl restart nginx`
239
- Open <http://wiki.domain.tld> in your browser
240
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
241
242
### NGINX on RHEL, CentOS, Rocky and derivates
243
244
- Install nginx via `dnf install nginx`
245
- Start NGINX and enable at boot: `sudo systemctl enable --now nginx`
246
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
247
- Create the `otterwiki.conf` in `/etc/nginx/conf.d/`
248
- Check the syntax via `nginx -t`
249
- Restart nginx via `systemctl restart nginx`
250
- Open <http://wiki.domain.tld> in your browser
251
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
252
253
See <https://www.redhat.com/sysadmin/setting-reverse-proxies-nginx> for a complete guide.
254
255
## Apache
256
257
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.
258
259
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
260
261
```
262
<VirtualHost *:*>
263
ServerName wiki.domain.tld
264
ProxyPreserveHost On
265
ProxyPass / http://0.0.0.0:8080/
266
ProxyPassReverse / http://0.0.0.0:8080/
267
</VirtualHost>
268
```
269
270
### Apache on Debian, Ubuntu and derivates
271
272
- Install apache2 via `apt install -y apache2`
273
- Enable proxy modules via `a2enmod proxy proxy_http`
274
- Create the `otterwiki.conf` config file in `/etc/apache2/site-available/`
275
- Enable the site via `a2ensite otterwiki`
276
- Restart apache2 `systemctl restart apache2`
277
- Open <http://wiki.domain.tld> in your browser
278
- Check `journalctl -xeu apache2.service` and `/var/log/apache2/error.log` for error messages.
279
280
### Apache on RHEL, CentOS, Rocky and derivates
281
282
- Install apache2 via `dnf install httpd`
679b7f Ralph Thesen 2024-05-05 09:04:15 283
- Start apache2 and enable at boot: `sudo systemctl enable --now httpd`
f1509e Ralph Thesen 2023-11-18 14:39:06 284
- Create the `otterwiki.conf` config file in `/etc/httpd/conf.d/`
285
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
286
- Restart apache2 via `systemctl restart httpd`
287
- Open <http://wiki.domain.tld> in your browser
288
- Check `journalctl -xeu httpd.service` and `/var/log/httpd/error_log` for error messages.
289
290
## Caddy
291
292
[Caddy](https://caddyserver.com/) is an open source webserver with a very light configuration that makes a fine reverse proxy.
293
294
After [installing](https://caddyserver.com/docs/install) caddy, configure `/etc/caddy/Caddyfile` with e.g.
295
296
```
297
domain.tld {
679b7f Ralph Thesen 2024-05-05 09:04:15 298
reverse_proxy localhost:8080
f1509e Ralph Thesen 2023-11-18 14:39:06 299
}
300
```
301
9fae76 Otterwiki Robot 2025-07-20 15:06:40 302
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.