Home A - Z Changelog
Page Index

An Otter Wiki

Blame

84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
1 
# Otterwiki Installation
2
https://otterwiki.com/Installation
3
4
From source as WSGI application with uwsgi
5
6
1. Install the prerequisites on Debian / Ubuntu
7
8
`apt install git build-essential python3-dev python3-venv`
9
10
2. Clone the otterwiki repository and enter the directory
11
```
12
git clone https://github.com/redimp/otterwiki.git
13
cd otterwiki
14
```
15
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
16
3. Create user for service (and create /opt/otterwiki)
17
```bash
18
sudo adduser --system \
19
--group \
20
--home /opt/otterwiki \
21
--shell /usr/sbin/nologin \
22
otterwiki
23
sudo chmod 750 /opt/otterwiki
24
sudo chown root /opt/otterwiki
25
```
26
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
27
3. Create and initialize the repository where the otterwiki data lives
28
```
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
29
sudo install -d -o otterwiki -g otterwiki -m 750 /var/lib/otterwiki
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
30
# initialize the empty repository
31
git init -b main app-data/repository
32
```
33
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
34
4. Create a minimal settings.cfg e.g. via sudo -i
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
35
```bash
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
36
echo "REPOSITORY=\"${PWD}/app-data/repository\"" >> settings.cfg
37
echo "SQLALCHEMY_DATABASE_URI=\"sqlite:///${PWD}/app-data/db.sqlite\"" >> settings.cfg
38
echo "SECRET_KEY=\"$(python3 -c 'import secrets; print(secrets.token_hex())')\"" >> settings.cfg
39
chgrp otterwiki settings.cfg
40
chmod 640 settings.cfg
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
41
```
42
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
43
5. Create a virtual environment and install An Otter Wiki (in /opt/otterwiki)
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
44
```bash
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
45
# create python virtual environment
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
46
python3 -m venv venv
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
47
# upgrade pip and install uwsgi
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
48
./venv/bin/pip install -U pip uwsgi
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
49
# install python application from current directory
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
50
./venv/bin/pip install .
51
```
52
53
6. Run uwsgi listening on the localhost port 8080
54
```bash
55
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
56
./venv/bin/uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
57
```
58
59
7. Open `http://127.0.0.1:8080` in your browser.
60
61
8. Register your account. The first account is an admin-account with access to the application settings.
62
63
9. Alternatively can you configure the application using the settings.cfg. For all configuration options please see Configuration.
64
65
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
66
```
67
[Unit]
68
Description=uWSGI server for An Otter Wiki
69
70
[Service]
71
User=www-data
72
Group=www-data
73
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
74
ExecStart=/path/to/an/otterwiki/venv/bin/uwsgi --http 127.0.0.1:8080 --enable-threads --die-on-term -w otterwiki.server:app
75
SyslogIdentifier=otterwiki
76
77
[Install]
78
WantedBy=multi-user.target
79
```
80
Make sure to adapt the /path/to and that the configured user can read and write the database and the repository folder.
81
82
11. Run `systemctl daemon-reload` and `systemctl start otterwiki.service`, check `systemctl status otterwiki.service` for errors.
83
:::info
84
Note
85
It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see Reverse Proxy below.
86
:::
87
88
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`.
89
90
# Reverse Proxy
91
A reverse proxy is a server that sits in front of web servers and forwards client (e.g. web browser) requests to those web servers. They are useful when hosting multiple services on a host and make it much easier to configure https. Neither An Otter Wiki itself nor the in the docker image provides https.
92
93
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For more detailed informations please check the corresponding software documentation.
94
95
Also check out Configuration for additional info on passing real IPs to the wiki.
96
97
## NGINX
98
This is a minimal example of a config that configures NGINX as a reverse proxy. The full documentation about NGINX as reverse proxy can be found here.
99
100
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
101
102
```
103
server {
104
server_name wiki.domain.tld;
105
listen 80;
106
location / {
107
proxy_set_header Host $http_host;
108
proxy_set_header X-Real-IP $remote_addr;
109
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
110
proxy_set_header X-Forwarded-Host $http_host;
111
proxy_set_header X-Forwarded-Proto $scheme;
112
proxy_pass http://127.0.0.1:8080;
113
client_max_body_size 64M; # for attachments of a size up to 64 Mb
114
}
115
}
116
```
117
### NGINX on Debian, Ubuntu and derivates
118
Install nginx via apt install -y nginx
119
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
120
- Check the syntax via `nginx -t`
121
- Restart nginx via `systemctl restart nginx`
122
- Open http://wiki.domain.tld in your browser
123
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
124
125
### Update Otterwiki
126
```bash
127
cd /path/to/otterwiki
128
129
git remote update origin
130
131
LATEST_RELEASE=$(git describe --tags $(git rev-list --tags --max-count=1))
132
133
git checkout -b "$LATEST_RELEASE" "$LATEST_RELEASE"
134
135
./venv/bin/pip install -U .
136
137
sudo systemctl restart otterwiki.service
752f61 Niklas Polke 2026-08-17 08:46:37
Update Backup sqlite3
138
```
139
140
### Backup sqlite
141
```bash
142
# in venv
143
python -c 'import sqlite3; src=sqlite3.connect("/srv/otterwiki/app-data/db.sqlite"); dst=sqlite3.connect("/home/pi/db.sqlite.backup"); src.backup(dst); dst.close(); src.close()'
144
```