commit 84d769

Commit `84d769`

2026-08-07 15:26:13 Niklas Polke: Create Otterwiki Installation

0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9

`/dev/null` .. `python/otterwiki installation.md`
@@ 0,0 1,107 @@
+	# 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 and initialize the repository where the otterwiki data lives
+	```
+	mkdir -p app-data/repository
+	# initialize the empty repository
+	git init -b main app-data/repository
+	```
+
+	4. Create a minimal settings.cfg e.g. via
+	```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
+	```
+
+	5. Create a virtual environment and install An Otter Wiki
+	```bash
+	python3 -m venv venv
+	./venv/bin/pip install -U pip uwsgi
+	./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.

Commit 84d769

Commit `84d769`