Otterwiki Installation

From source as WSGI application with uwsgi

Install the prerequisites on Debian / Ubuntu

apt install git build-essential python3-dev python3-venv

Clone the otterwiki repository and enter the directory

git clone https://github.com/redimp/otterwiki.git
cd otterwiki

Create user for service (and create /opt/otterwiki)

sudo adduser --system \
  --group \
  --home /opt/otterwiki \
  --shell /usr/sbin/nologin \
  otterwiki
sudo chmod 750 /opt/otterwiki
sudo chown root /opt/otterwiki

Create and initialize the repository where the otterwiki data lives

sudo install -d -o otterwiki -g otterwiki -m 750 /var/lib/otterwiki
# initialize the empty repository
git init -b main app-data/repository

Create a minimal settings.cfg e.g. via sudo -i

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

Create a virtual environment and install An Otter Wiki (in /opt/otterwiki)

# create python virtual environment
python3 -m venv venv
# upgrade pip and install uwsgi
./venv/bin/pip install -U pip uwsgi
# install python application from current directory
./venv/bin/pip install .

Run uwsgi listening on the localhost port 8080

export OTTERWIKI_SETTINGS=$PWD/settings.cfg
./venv/bin/uwsgi --http 127.0.0.1:8080 --master --enable-threads --die-on-term -w otterwiki.server:app

Open http://127.0.0.1:8080 in your browser.
Register your account. The first account is an admin-account with access to the application settings.
Alternatively can you configure the application using the settings.cfg. For all configuration options please see Configuration.
Create a service file e.g. /etc/systemd/system/otterwiki.service

[Unit]
Description=uWSGI server for An Otter Wiki

[Service]
User=www-data
Group=www-data
Environment=OTTERWIKI_SETTINGS=/path/to/the/settings.cfg
ExecStart=/path/to/an/otterwiki/venv/bin/uwsgi --http 127.0.0.1:8080 --enable-threads --die-on-term -w otterwiki.server:app
SyslogIdentifier=otterwiki

[Install]
WantedBy=multi-user.target

Make sure to adapt the /path/to and that the configured user can read and write the database and the repository folder.

Run systemctl daemon-reload and systemctl start otterwiki.service, check systemctl status otterwiki.service for errors. :::info Note It's highly recommended to use a webserver as reverse proxy to connect to uwsgi, see Reverse Proxy below. :::

If you want to skip the reverse proxy consider to bind uwsgi not to just the local ip 127.0.0.1, but to all ips of the host running An Otter Wiki with --http 0.0.0.0:8080.

Reverse Proxy

A reverse proxy is a server that sits in front of web servers and forwards client (e.g. web browser) requests to those web servers. They are useful when hosting multiple services on a host and make it much easier to configure https. Neither An Otter Wiki itself nor the in the docker image provides https.

Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For more detailed informations please check the corresponding software documentation.

Also check out Configuration for additional info on passing real IPs to the wiki.

NGINX

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.

It's assumed that An Otter Wiki is running either in a docker container or as a uwsgi process and listening on port 8080.

server {
    server_name wiki.domain.tld;
    listen 80;
    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8080;
        client_max_body_size 64M; # for attachments of a size up to 64 Mb
    }
}

NGINX on Debian, Ubuntu and derivates

Install nginx via apt install -y nginx

Create the otterwiki.conf in /etc/nginx/sites-enabled/
Check the syntax via nginx -t
Restart nginx via systemctl restart nginx
Open http://wiki.domain.tld in your browser
Check journalctl -xeu nginx and /var/log/nginx/error.log for errors.

Update Otterwiki

cd /path/to/otterwiki

git remote update origin

LATEST_RELEASE=$(git describe --tags $(git rev-list --tags --max-count=1))

git checkout -b "$LATEST_RELEASE" "$LATEST_RELEASE"

./venv/bin/pip install -U .

sudo systemctl restart otterwiki.service
``