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
3
The recommend way of running An Otter Wiki is via [[docker compose|Installation#using-docker-compose]].
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
9
10
As URLs as dedicated domain (e.g. `wiki.domain.tld`) is required, it can not be mapped into a subfolder.
11
12
## Using docker
13
14
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`.
15
16
Make sure you have [docker](https://docs.docker.com/engine/install/) installed.
17
18
To run an otter wiki via docker, listening on port 8080 and using a local directory for data persistency, use the following command:
19
```
20
docker run -p 8080:80 --name otterwiki redimp/otterwiki:2.0
21
```
22
Open the wiki via http://127.0.0.1:8080 if you are running the docker command on your machine.
23
24
You can configure the application with environment variables e.g.
25
```
26
-e SITE_NAME="My Wiki" -e SITE_DESCRIPTION="An otter wiki run via docker"
27
```
28
For all configuration options please see [[Configuration]].
29
30
## Using docker compose
31
32
The recommended way of running An Otter Wiki is via `docker compose`.
33
34
1. Create a `docker-compose.yaml` file
35
36
```yaml
37
version: '3'
38
services:
39
otterwiki:
40
image: redimp/otterwiki:2.0
41
restart: unless-stopped
42
ports:
43
- 8080:80
44
volumes:
45
- ./app-data:/app-data
46
```
47
48
2. Run `docker compose up -d`
49
3. Access the wiki via http://127.0.0.1:8080 if run on your machine.
50
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.
51
5. Customize the settings to your liking.
52
6. It's highly recommended to use a webserver as reverse proxy to connect to the docker process, see [Reverse Proxy](#reverse-proxy) below.
53
54
Alternativly you can configure the application using environment variables, for example:
55
56
```yaml
57
version: '3'
58
services:
59
otterwiki:
60
image: redimp/otterwiki:2.0
61
restart: unless-stopped
62
ports:
63
- 8080:80
64
volumes:
65
- ./app-data:/app-data
66
environemnt:
67
MAIL_DEFAULT_SENDER: no-reply@example.com
68
MAIL_SERVER: smtp.server.tld
69
MAIL_PORT: 465
70
MAIL_USERNAME: otterwiki@example.com
71
MAIL_PASSWORD: somepassword
72
MAIL_USE_SSL: True
73
```
74
75
For all configuration options please see [[Configuration]].
76
77
## podman and podman-compose
78
79
An Otter Wiki can be run with `podman` and `podman-compose` in the same way as with` docker` and `docker compose` please see above.
80
81
## From source as WSGI application with uwsgi
82
83
1. Install the prerequisites
84
85
i. Debian / Ubuntu
86
```
87
apt install git build-essential python3-dev python3-venv
88
```
89
ii. RHEL8 / Fedora / CentOS8 / Rocky Linux 8
90
```
91
yum install make python3-devel
92
```
93
2. Clone the otterwiki repository and enter the directory
94
```
95
git clone https://github.com/redimp/otterwiki.git
96
cd otterwiki
97
```
98
3. Create and initialize the repository where the otterwiki data lives
99
```bash
100
mkdir -p app-data/repository
101
# initialize the empty repository
102
git init app-data/repository
103
```
104
4. Create a minimal `settings.cfg` e.g. via
105
```bash
106
echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
107
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
108
echo "SECRET_KEY='$(echo $RANDOM | md5sum | head -c 16)'" >> settings.cfg
109
```
110
5. Create a virtual environment and install An Otter Wiki
111
```
112
python3 -m venv venv
113
./venv/bin/pip install -U pip uwsgi
114
./venv/bin/pip install .
115
```
116
6. Run uwsgi listening on the localhost port 8080
117
```bash
118
export OTTERWIKI_SETTINGS=$PWD/settings.cfg
119
./venv/bin/uwsgi --http 127.0.0.1:8080 --master -enable-threads --die-on-term -w otterwiki.server:app
120
```
121
7. Open http://127.0.0.1:8080 in your browser.
122
8. Register your account. The first account is an admin-account with access to the application settings.
123
9. Alternatively can you configure the application using the `settings.cfg`. For all configuration options please see [[Configuration]].
124
10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`
125
126
```systemd
127
[Unit]
128
Description=uWSGI server for An Otter Wiki
129
130
[Service]
131
User=www-data
132
Group=www-data
133
WorkingDirectory=/path/to/an/otterwiki
134
ExecStart=/path/to/an/otterwiki/env/bin/uwsgi --http 127.0.0.1:8080 -enable-threads --die-on-term -w otterwiki.server:app
135
SyslogIdentifier=otterwiki
136
137
[Install]
138
WantedBy=multi-user.target
139
```
140
141
It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see [Reverse Proxy](#reverse-proxy) below.
142
143
# Reverse Proxy
144
145
A reverse proxy is a server that sits in front of web servers and forwards
146
client (e.g. web browser) requests to those web servers. They are useful
147
when hosting multiple services on a host and make it much easier to configure
148
https. Neither An Otter Wiki itself nor the in the docker image provides https.
149
150
Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For complete documention please check the corresponding software documention.
151
152
## NGINX
153
154
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](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).
155
156
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
157
158
```nginx
159
server {
160
server_name wiki.domain.tld;
161
listen 80;
162
location / {
163
proxy_set_header Host $http_host;
164
proxy_set_header X-Real-IP $remote_addr;
165
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
166
proxy_set_header X-Forwarded-Host $http_host;
167
proxy_pass http://127.0.0.1:8080;
168
}
169
}
170
```
171
172
### NGINX on Debian, Ubuntu and derivates
173
174
- Install nginx via `apt install -y nginx`
175
- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`
176
- Check the syntax via `nginx -t`
177
- Restart nginx via `systemctl restart nginx`
178
- Open <http://wiki.domain.tld> in your browser
179
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
180
181
### NGINX on RHEL, CentOS, Rocky and derivates
182
183
- Install nginx via `dnf install nginx`
184
- Start NGINX and enable at boot: `sudo systemctl enable --now nginx`
185
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
186
- Create the `otterwiki.conf` in `/etc/nginx/conf.d/`
187
- Check the syntax via `nginx -t`
188
- Restart nginx via `systemctl restart nginx`
189
- Open <http://wiki.domain.tld> in your browser
190
- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.
191
192
See <https://www.redhat.com/sysadmin/setting-reverse-proxies-nginx> for a complete guide.
193
194
## Apache
195
196
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.
197
198
It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.
199
200
```
201
<VirtualHost *:*>
202
ServerName wiki.domain.tld
203
ProxyPreserveHost On
204
ProxyPass / http://0.0.0.0:8080/
205
ProxyPassReverse / http://0.0.0.0:8080/
206
</VirtualHost>
207
```
208
209
### Apache on Debian, Ubuntu and derivates
210
211
- Install apache2 via `apt install -y apache2`
212
- Enable proxy modules via `a2enmod proxy proxy_http`
213
- Create the `otterwiki.conf` config file in `/etc/apache2/site-available/`
214
- Enable the site via `a2ensite otterwiki`
215
- Restart apache2 `systemctl restart apache2`
216
- Open <http://wiki.domain.tld> in your browser
217
- Check `journalctl -xeu apache2.service` and `/var/log/apache2/error.log` for error messages.
218
219
### Apache on RHEL, CentOS, Rocky and derivates
220
221
- Install apache2 via `dnf install httpd`
222
- Start apache2 and enable at boot: `sudo systemctl enable --now httpd`
223
- Create the `otterwiki.conf` config file in `/etc/httpd/conf.d/`
224
- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`
225
- Restart apache2 via `systemctl restart httpd`
226
- Open <http://wiki.domain.tld> in your browser
227
- Check `journalctl -xeu httpd.service` and `/var/log/httpd/error_log` for error messages.
228
229
## Caddy
230
231
[Caddy](https://caddyserver.com/) is an open source webserver with a very light configuration that makes a fine reverse proxy.
232
233
After [installing](https://caddyserver.com/docs/install) caddy, configure `/etc/caddy/Caddyfile` with e.g.
234
235
```
236
domain.tld {
237
reverse_proxy localhost:8080
238
}
239
```
240
241
With a server accessible from the internet, `domain.tld` beeing a proper domain name with A/AAAA DNS records pointing to the server, caddy will [automatically](https://caddyserver.com/docs/automatic-https) serve HTTPS.