Home A - Z
Page Index

An Otter Wiki

Blame

bd3f6d Jason Tubnor 2025-01-22 11:55:38 1 
# Installation of Otter Wiki in a FreeBSD Jail
2
3
**Date:** 20250122
4
5
**Scope:**
6
7
This document will cover the installation of Otter Wiki into an existing or new FreeBSD jail utilising the FreeBSD package and Otter Wiki repositories. The creation of a FreeBSD jail will not be covered here, and any generically built jail will work.
8
9
Launching and management of the Otter Wiki service will be through the supervisor daemon and not the existing rc.d service.
10
11
**Instructions:**
12
13
Once the jail is built, launched and patched, enter the jail as root to install the initial packages.
14
```
15
pkg install git-lite openjpeg python3 py311-pip py311-sqlite3 py311-supervisor uwsgi-py311
16
```
17
By default, FreeBSD python3 meta package will not install a ‘python’ symbolic link to python3. This needs to be created for the Otter Wiki scripts to work correctly:
18
```
19
cd /usr/local/bin ; ln -s python3 python
20
```
21
Add an unprivileged user to run the Otter Wiki under. Otter Wiki will be installed in this users home directory and run from there. This document will use ‘otterwiki’ as the username and /home/otterwiki as the home directory.
22
23
Switch to the otterwiki user:
24
```
25
su - otterwiki
26
```
27
Following the projects source installation instructions listed as [From source as WSGI application with uwsgi](https://otterwiki.com/Installation#from-source-as-wsgi-application-with-uwsgi) (always refer to these as this installation summary may get out of date).
28
29
Create a supervisor log directory and then clone the project into the otterwiki home directory and set up the wiki storage and repository locations:
30
```
31
mkdir logs
32
git clone https://github.com/redimp/otterwiki.git
33
cd otterwiki
34
mkdir -p app-data/repository
35
git init -b main app-data/repository
36
```
37
Create the Otter Wiki settings.cfg file:
38
```
39
echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
40
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
41
echo "SECRET_KEY='$(python -c 'import secrets; print(secrets.token_hex())')'" >> settings.cfg
42
```
43
Create the virtual environment that uwsgi will use to run Otter Wiki from:
44
```
45
pip install .
46
```
47
Exit the otterwiki user to return back to the root user.
48
49
Change directory to the local etc directory, create an include directory for the otterwiki supervisor configuration file and modify the supervisord.conf file to read in \*.conf files within this directory:
50
```
51
cd /usr/local/etc
52
mkdir supervisord.conf.d
53
```
54
The changes made to supervisord.conf:
55
```
56
--- supervisord.conf.sample 2025-01-09 12:47:26.000000000 +1100
57
+++ supervisord.conf 2025-01-21 09:45:01.427799000 +1100
58
@@ -166,5 +166,5 @@ serverurl=unix:///var/run/supervisor/supervisor.sock ;
59
; interpreted as relative to this file. Included files *cannot*
60
; include files themselves.
61
62
-;[include]
63
-;files = relative/directory/*.ini
64
+[include]
65
+files = supervisord.conf.d/*.conf
66
```
67
And example of an /usr/local/etc/supervisord.conf.d/otterwiki.conf :
68
```
69
[program:otterwiki]
70
command=uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
71
directory=/home/otterwiki/otterwiki
72
autostart=true
73
autorestart=true
74
user=otterwiki
75
environment =
76
HOME=/home/otterwiki,
77
USER=otterwiki,
78
PATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin",
79
PWD=/home/otterwiki/otterwiki,
80
OTTERWIKI_SETTINGS=/home/otterwiki/otterwiki/settings.cfg
81
stdout_logfile=/home/otterwiki/logs/stdout.log
82
stdout_logfile_maxbytes=50MB
83
stdout_logfile_backups=10
84
stderr_logfile=/home/otterwiki/logs/stderr.log
85
stderr_logfile_maxbytes=50MB
86
stderr_logfile_backups=10
87
```
88
Once this has been completed, Otter Wiki can be started and will be listening on localhost port 8080. At this point a reverse proxy can be installed and configured to point to 127.0.0.1:8080 to access the wiki.
89
90
The official documentation has a [minimal non-encrypted Nginx configuration](https://otterwiki.com/Installation#nginx), below is a configuration that will work with modern browsers as long as you have a certificate installed:
91
```
92
server {
93
listen 80;
94
listen [::]:80;
95
server_name wiki.example.com;
96
return 301 https://wiki.example.com$request_uri;
97
}
98
99
server {
100
listen 443 ssl;
101
listen [::]:443 ssl;
102
server_name wiki.example.com;
103
104
ssl_certificate /var/db/acme/certs/wiki.example.com_ecc/fullchain.cer;
105
ssl_certificate_key /var/db/acme/certs/wiki.example.com_ecc/wiki.example.com.key;
106
ssl_trusted_certificate /usr/local/etc/ssl/cert.pem;
107
ssl_dhparam /var/db/acme/certs/wiki.example.com_ecc/wiki.example.com.dhpem;
108
109
ssl_session_timeout 15m;
110
ssl_session_tickets off;
111
112
ssl_protocols TLSv1.2 TLSv1.3;
113
ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5;
114
ssl_prefer_server_ciphers off;
115
ssl_stapling on;
116
ssl_stapling_verify on;
117
add_header Strict-Transport-Security "max-age=15552000" always;
118
119
access_log /var/log/nginx/wiki.example.com.access.log main;
120
121
proxy_set_header HOST $host;
122
proxy_set_header X-Forwarded-Proto $scheme;
123
proxy_set_header X-Real-IP $remote_addr;
124
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
125
client_max_body_size 64M;
126
127
location / {
128
proxy_pass http://127.0.0.1:8080;
129
}
130
131
}
132
```
133
Start Nginx, navigate to wiki.example.com, create an admin account (the first account created will be the admin account) and then [complete the configuration](https://otterwiki.com/Configuration) to meet your requirements.
134
135
==End of Document==