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
16
3. Create and initialize the repository where the otterwiki data lives
17
```
18
mkdir -p app-data/repository
19
# initialize the empty repository
20
git init -b main app-data/repository
21
```
22
23
4. Create a minimal settings.cfg e.g. via
24
```bash
25
echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
26
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
27
echo "SECRET_KEY='$(python3 -c 'import secrets; print(secrets.token_hex())')'" >> settings.cfg
28
```
29
30
5. Create a virtual environment and install An Otter Wiki
31
```bash
32
python3 -m venv venv
33
./venv/bin/pip install -U pip uwsgi
34
./venv/bin/pip install .
35
```
36
37
6. Run uwsgi listening on the localhost port 8080
38
```bash
39
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
40
./venv/bin/uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
41
```
42
43
7. Open `http://127.0.0.1:8080` in your browser.
44
45
8. Register your account. The first account is an admin-account with access to the application settings.
46
47
9. Alternatively can you configure the application using the settings.cfg. For all configuration options please see Configuration.
48
49
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
50
```
51
[Unit]
52
Description=uWSGI server for An Otter Wiki
53
54
[Service]
55
User=www-data
56
Group=www-data
57
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
58
ExecStart=/path/to/an/otterwiki/venv/bin/uwsgi --http 127.0.0.1:8080 --enable-threads --die-on-term -w otterwiki.server:app
59
SyslogIdentifier=otterwiki
60
61
[Install]
62
WantedBy=multi-user.target
63
```
64
Make sure to adapt the /path/to and that the configured user can read and write the database and the repository folder.
65
66
11. Run `systemctl daemon-reload` and `systemctl start otterwiki.service`, check `systemctl status otterwiki.service` for errors.
67
:::info
68
Note
69
It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see Reverse Proxy below.
70
:::
71
72
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`.
73
74
# Reverse Proxy
75
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.
76
77
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For more detailed informations please check the corresponding software documentation.
78
79
Also check out Configuration for additional info on passing real IPs to the wiki.
80
81
## NGINX
82
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.
83
84
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
85
86
```
87
server {
88
server_name wiki.domain.tld;
89
listen 80;
90
location / {
91
proxy_set_header Host $http_host;
92
proxy_set_header X-Real-IP $remote_addr;
93
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
94
proxy_set_header X-Forwarded-Host $http_host;
95
proxy_set_header X-Forwarded-Proto $scheme;
96
proxy_pass http://127.0.0.1:8080;
97
client_max_body_size 64M; # for attachments of a size up to 64 Mb
98
}
99
}
100
```
101
### NGINX on Debian, Ubuntu and derivates
102
Install nginx via apt install -y nginx
103
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
104
- Check the syntax via `nginx -t`
105
- Restart nginx via `systemctl restart nginx`
106
- Open http://wiki.domain.tld in your browser
107
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.