# Otterwiki Installation
https://otterwiki.com/Installation

From source as WSGI application with uwsgi

1. Install the prerequisites on Debian / Ubuntu

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

2. Clone the otterwiki repository and enter the directory
```
git clone https://github.com/redimp/otterwiki.git
cd otterwiki
```

3. Create user for service (and create /opt/otterwiki)
```bash
sudo adduser --system \
  --group \
  --home /opt/otterwiki \
  --shell /usr/sbin/nologin \
  otterwiki
sudo chmod 755 /opt/otterwiki
sudo chown root /opt/otterwiki
```

3. 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
```

4. Create a minimal settings.cfg e.g. via sudo -i
```bash
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
```

5. Create a virtual environment and install An Otter Wiki (in /opt/otterwiki)
```bash
# create python virtual environment
python3 -m venv venv
# upgrade pip and install uwsgi
./venv/bin/pip install -U pip uwsgi
./venv/bin/pip install gunicorn
# install python application from current directory
./venv/bin/pip install .
```

6. Run uwsgi listening on the localhost port 8080
```bash
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
```

7. Open `http://127.0.0.1:8080` in your browser.

8. Register your account. The first account is an admin-account with access to the application settings.

9. Alternatively can you configure the application using the settings.cfg. For all configuration options please see Configuration.

10. 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.

11. 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
```bash
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
```

### Backup sqlite
```bash
# in venv
python -c 'import sqlite3; src=sqlite3.connect("/srv/otterwiki/app-data/db.sqlite"); dst=sqlite3.connect("/home/pi/db.sqlite.backup"); src.backup(dst); dst.close(); src.close()'
```

### Backup git
```bash
git bundle create repo-backup.bundle --all
git clone repo-backup.bundle wiederhergestellt
```