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