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