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
fa79ef Niklas Polke 2026-08-17 12:06:28
Update Otterwiki Installation
23
sudo chmod 755 /opt/otterwiki
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of 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
fa79ef Niklas Polke 2026-08-17 12:06:28
Update Otterwiki Installation
49
./venv/bin/pip install gunicorn
d189d4 Niklas Polke 2026-08-16 23:27:36
Update Installation and Update of Otterwiki
50
# install python application from current directory
84d769 Niklas Polke 2026-08-07 15:26:13
Create Otterwiki Installation
51
./venv/bin/pip install .
52
```
53
54
6. Run uwsgi listening on the localhost port 8080
55
```bash
56
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
57
./venv/bin/uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
58
```
59
60
7. Open `http://127.0.0.1:8080` in your browser.
61
62
8. Register your account. The first account is an admin-account with access to the application settings.
63
64
9. Alternatively can you configure the application using the settings.cfg. For all configuration options please see Configuration.
65
66
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
67
```
68
[Unit]
69
Description=uWSGI server for An Otter Wiki
70
71
[Service]
72
User=www-data
73
Group=www-data
74
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
75
ExecStart=/path/to/an/otterwiki/venv/bin/uwsgi --http 127.0.0.1:8080 --enable-threads --die-on-term -w otterwiki.server:app
76
SyslogIdentifier=otterwiki
77
78
[Install]
79
WantedBy=multi-user.target
80
```
81
Make sure to adapt the /path/to and that the configured user can read and write the database and the repository folder.
82
83
11. Run `systemctl daemon-reload` and `systemctl start otterwiki.service`, check `systemctl status otterwiki.service` for errors.
84
:::info
85
Note
86
It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see Reverse Proxy below.
87
:::
88
89
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`.
90
91
# Reverse Proxy
92
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.
93
94
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For more detailed informations please check the corresponding software documentation.
95
96
Also check out Configuration for additional info on passing real IPs to the wiki.
97
98
## NGINX
99
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.
100
101
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
102
103
```
104
server {
105
server_name wiki.domain.tld;
106
listen 80;
107
location / {
108
proxy_set_header Host $http_host;
109
proxy_set_header X-Real-IP $remote_addr;
110
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
111
proxy_set_header X-Forwarded-Host $http_host;
112
proxy_set_header X-Forwarded-Proto $scheme;
113
proxy_pass http://127.0.0.1:8080;
114
client_max_body_size 64M; # for attachments of a size up to 64 Mb
115
}
116
}
117
```
118
### NGINX on Debian, Ubuntu and derivates
119
Install nginx via apt install -y nginx
120
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
121
- Check the syntax via `nginx -t`
122
- Restart nginx via `systemctl restart nginx`
123
- Open http://wiki.domain.tld in your browser
124
- 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
125
126
### Update Otterwiki
127
```bash
128
cd /path/to/otterwiki
129
130
git remote update origin
131
132
LATEST_RELEASE=$(git describe --tags $(git rev-list --tags --max-count=1))
133
134
git checkout -b "$LATEST_RELEASE" "$LATEST_RELEASE"
135
136
./venv/bin/pip install -U .
137
138
sudo systemctl restart otterwiki.service
752f61 Niklas Polke 2026-08-17 08:46:37
Update Backup sqlite3
139
```
140
141
### Backup sqlite
142
```bash
143
# in venv
144
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()'
145
```
8a246a Niklas Polke 2026-08-17 08:49:06
Update Backup git
146
147
### Backup git
148
```bash
149
git bundle create repo-backup.bundle --all
150
git clone repo-backup.bundle wiederhergestellt
151
```