Blame

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