Installation of Otter Wiki in a FreeBSD Jail

Date: 20250122

Scope:

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.

Launching and management of the Otter Wiki service will be through the supervisor daemon and not the existing rc.d service.

Instructions:

Once the jail is built, launched and patched, enter the jail as root to install the initial packages.

pkg install git-lite openjpeg python3 py311-pip py311-sqlite3 py311-supervisor uwsgi-py311

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:

cd /usr/local/bin ; ln -s python3 python

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.

Switch to the otterwiki user:

su - otterwiki

Following the projects source installation instructions listed as From source as WSGI application with uwsgi (always refer to these as this installation summary may get out of date).

Create a supervisor log directory and then clone the project into the otterwiki home directory and set up the wiki storage and repository locations:

mkdir logs
git clone https://github.com/redimp/otterwiki.git
cd otterwiki
mkdir -p app-data/repository
git init -b main app-data/repository

Create the Otter Wiki settings.cfg file:

echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
echo "SECRET_KEY='$(python -c 'import secrets; print(secrets.token_hex())')'" >> settings.cfg

Create the virtual environment that uwsgi will use to run Otter Wiki from:

pip install .

Exit the otterwiki user to return back to the root user.

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:

cd /usr/local/etc
mkdir supervisord.conf.d

The changes made to supervisord.conf:

--- supervisord.conf.sample     2025-01-09 12:47:26.000000000 +1100
+++ supervisord.conf    2025-01-21 09:45:01.427799000 +1100
@@ -166,5 +166,5 @@ serverurl=unix:///var/run/supervisor/supervisor.sock ;
 ; interpreted as relative to this file.  Included files *cannot*
 ; include files themselves.

-;[include]
-;files = relative/directory/*.ini
+[include]
+files = supervisord.conf.d/*.conf

And example of an /usr/local/etc/supervisord.conf.d/otterwiki.conf :

[program:otterwiki]
command=uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app
directory=/home/otterwiki/otterwiki
autostart=true
autorestart=true
user=otterwiki
environment =
  HOME=/home/otterwiki,
  USER=otterwiki,
  PATH="/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin",
  PWD=/home/otterwiki/otterwiki,
  OTTERWIKI_SETTINGS=/home/otterwiki/otterwiki/settings.cfg
stdout_logfile=/home/otterwiki/logs/stdout.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10
stderr_logfile=/home/otterwiki/logs/stderr.log
stderr_logfile_maxbytes=50MB
stderr_logfile_backups=10

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.

The official documentation has a minimal non-encrypted Nginx configuration, below is a configuration that will work with modern browsers as long as you have a certificate installed:

server {
        listen 80;
        listen [::]:80;
        server_name wiki.example.com;
        return 301 https://wiki.example.com$request_uri;
}

server {
        listen 443 ssl;
        listen [::]:443 ssl;
        server_name wiki.example.com;

        ssl_certificate      /var/db/acme/certs/wiki.example.com_ecc/fullchain.cer;
        ssl_certificate_key  /var/db/acme/certs/wiki.example.com_ecc/wiki.example.com.key;
        ssl_trusted_certificate /usr/local/etc/ssl/cert.pem;
        ssl_dhparam /var/db/acme/certs/wiki.example.com_ecc/wiki.example.com.dhpem;

        ssl_session_timeout  15m;
        ssl_session_tickets off;

        ssl_protocols TLSv1.2 TLSv1.3;
        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;
        ssl_prefer_server_ciphers  off;
        ssl_stapling on;
        ssl_stapling_verify on;
        add_header Strict-Transport-Security "max-age=15552000" always;

        access_log  /var/log/nginx/wiki.example.com.access.log  main;

        proxy_set_header HOST $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        client_max_body_size 64M;

        location / {
                proxy_pass   http://127.0.0.1:8080;
        }

}

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 to meet your requirements.

End of Document