Installation - blame (14546e)

Blame

f1509e	Ralph Thesen	2023-11-18 14:39:06
Added documentation for installing An Otter Wiki

# Installation

The recommend way of running An Otter Wiki is via [[docker compose|Installation#using-docker-compose]].

## Requirements

The **CPU** requirements are pretty low, you can run it on a Raspberry Pi 1 A (ARMv6). The **RAM** required is around 100MiB (according to `docker stats`). The required disk **storage** depends on the content, please keep in mind, that the backend is a git repository that never forgets: Deleting a page or an attachment does not free up any space. The wiki needs no internet access. Clients using the wiki need only access to the server running the wiki, so it can run in an environment which is _isolated_ from the internet.

As URLs as dedicated domain (e.g. `wiki.domain.tld`) is required, it can not be mapped into a subfolder.

f7923b	Ralph Thesen	2023-12-06 16:58:57
Update requirements: Clients need javascript

Client requirement: Javascript must be activated in your browser to use the wiki.

ab255a	Ralph Thesen	2023-11-26 13:35:43
Updated docker cli command

## Using docker cli

f1509e	Ralph Thesen	2023-11-18 14:39:06
Added documentation for installing An Otter Wiki

An Otter Wiki is published as a Docker image on Docker hub as [`redimp/otterwiki`](https://hub.docker.com/r/redimp/otterwiki). The stable images are build for the plattforms `amd64`, `arm64`, `armv7` and `armv6`. 

Make sure you have [docker](https://docs.docker.com/engine/install/) installed.

ab255a	Ralph Thesen	2023-11-26 13:35:43
Updated docker cli command

To run an otter wiki via docker cli, listening on port 8080 and using a local directory for data persistency, use the following command:

```bash

docker run --name otterwiki \

	-p 8080:80 \

    -v $PWD/app-data:/app-data \

14546e	Ralph Thesen	2024-01-03 11:15:44
use image tag :2 instead of :2.0

redimp/otterwiki:2

f1509e	Ralph Thesen	2023-11-18 14:39:06
Added documentation for installing An Otter Wiki

```

Open the wiki via http://127.0.0.1:8080 if you are running the docker command on your machine.

You can configure the application with environment variables e.g.

```

-e SITE_NAME="My Wiki" -e SITE_DESCRIPTION="An otter wiki run via docker"

```

For all configuration options please see [[Configuration]].

## Using docker compose

The recommended way of running An Otter Wiki is via `docker compose`.

1. Create a `docker-compose.yaml` file

```yaml

    version: '3'

    services:

      otterwiki:

14546e	Ralph Thesen	2024-01-03 11:15:44
use image tag :2 instead of :2.0

        image: redimp/otterwiki:2

f1509e	Ralph Thesen	2023-11-18 14:39:06
Added documentation for installing An Otter Wiki

        restart: unless-stopped

        ports:

          - 8080:80

        volumes:

          - ./app-data:/app-data

```

2. Run `docker compose up -d`

3. Access the wiki via http://127.0.0.1:8080 if run on your machine.

4. Register your account. The first account is an admin-account with access to the application settings. The first accounts email address doesn't need to be confirmed nor has the account to be activated.

5. Customize the settings to your liking.

6. It's highly recommended to use a webserver as reverse proxy to connect to  the docker process, see [Reverse Proxy](#reverse-proxy) below.

Alternativly you can configure the application using environment variables, for example:

```yaml

version: '3'

services:

  otterwiki:

14546e	Ralph Thesen	2024-01-03 11:15:44
use image tag :2 instead of :2.0

    image: redimp/otterwiki:2

f1509e	Ralph Thesen	2023-11-18 14:39:06
Added documentation for installing An Otter Wiki

    restart: unless-stopped

    ports:

    - 8080:80

    volumes:

    - ./app-data:/app-data

    environemnt:

      MAIL_DEFAULT_SENDER: no-reply@example.com

      MAIL_SERVER: smtp.server.tld

	  MAIL_PORT: 465

      MAIL_USERNAME: otterwiki@example.com

	  MAIL_PASSWORD: somepassword

	  MAIL_USE_SSL: True

```

For all configuration options please see [[Configuration]].

## podman and podman-compose

An Otter Wiki can be run with `podman` and `podman-compose` in the same way as with` docker` and `docker compose` please see above.

## From source as WSGI application with uwsgi

1. Install the prerequisites

i. Debian / Ubuntu

```

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

```

ii. RHEL8 / Fedora / CentOS8 / Rocky Linux 8

```

yum install make python3-devel

```

2. Clone the otterwiki repository and enter the directory

```

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

100

cd otterwiki

101

```

102

3. Create and initialize the repository where the otterwiki data lives

103

```bash

104

    mkdir -p app-data/repository

105

# initialize the empty repository

106

    git init app-data/repository

107

```

108

4. Create a minimal `settings.cfg` e.g. via

109

```bash

110

    echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg

111

	echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg

112

	echo "SECRET_KEY='$(echo $RANDOM | md5sum | head -c 16)'" >> settings.cfg 

113

```

114

5. Create a virtual environment and install An Otter Wiki

115

```

116

python3 -m venv venv

117

./venv/bin/pip install -U pip uwsgi

118

./venv/bin/pip install .

119

```

120

6. Run uwsgi listening on the localhost port 8080

121

```bash

122

    export OTTERWIKI_SETTINGS=$PWD/settings.cfg

123

    ./venv/bin/uwsgi --http 127.0.0.1:8080 --master -enable-threads --die-on-term -w otterwiki.server:app

124

```

125

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

126

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

127

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

128

10. Create a service file e.g. `/etc/systemd/system/otterwiki.service`

129

130

```systemd

131

[Unit]

132

  Description=uWSGI server for An Otter Wiki

133

134

[Service]

135

  User=www-data

136

  Group=www-data

137

  WorkingDirectory=/path/to/an/otterwiki

138

  ExecStart=/path/to/an/otterwiki/env/bin/uwsgi --http 127.0.0.1:8080 -enable-threads --die-on-term -w otterwiki.server:app

139

  SyslogIdentifier=otterwiki

140

141

[Install]

142

  WantedBy=multi-user.target

143

```

144

145

It's highly recommended to use a webserver as reverse proxy to connect to  uwsgi, see [Reverse Proxy](#reverse-proxy) below.

146

147

# Reverse Proxy

148

149

A reverse proxy is a server that sits in front of web servers and forwards

150

client (e.g. web browser) requests to those web servers. They are useful

151

when hosting multiple services on a host and make it much easier to configure

152

https. Neither An Otter Wiki itself nor the in the docker image provides https.

153

154

Mini how-tos for configuring Apache, NGINX and Caddy are provided below. For complete documention please check the corresponding software documention.

155

156

## NGINX

157

158

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](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/).

159

160

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

161

162

```nginx

163

server {

164

    server_name wiki.domain.tld;

165

    listen 80;

166

    location / {

167

       proxy_set_header Host $http_host;

168

       proxy_set_header X-Real-IP $remote_addr;

169

       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

170

       proxy_set_header X-Forwarded-Host $http_host;

171

       proxy_pass http://127.0.0.1:8080;

172

}

173

}

174

```

175

176

### NGINX on Debian, Ubuntu and derivates

177

178

- Install nginx via `apt install -y nginx`

179

- Create the `otterwiki.conf` in `/etc/nginx/sites-enabled/`

180

- Check the syntax via `nginx -t`

181

- Restart nginx via `systemctl restart nginx`

182

- Open <http://wiki.domain.tld> in your browser

183

- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.

184

185

### NGINX on RHEL, CentOS, Rocky and derivates

186

187

- Install nginx via `dnf install nginx`

188

- Start NGINX and enable at boot: `sudo systemctl enable --now nginx`

189

- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`

190

- Create the `otterwiki.conf` in `/etc/nginx/conf.d/`

191

- Check the syntax via `nginx -t`

192

- Restart nginx via `systemctl restart nginx`

193

- Open <http://wiki.domain.tld> in your browser

194

- Check `journalctl -xeu nginx` and `/var/log/nginx/error.log` for errors.

195

196

See <https://www.redhat.com/sysadmin/setting-reverse-proxies-nginx> for a complete guide.

197

198

## Apache

199

200

This is a minimal example how to configure Apache as reverse proxy. Please see the [Apache documentation](https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html) for complete details.

201

202

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

203

204

```

205

206

ServerName wiki.domain.tld

207

ProxyPreserveHost On

208

ProxyPass / http://0.0.0.0:8080/

209

ProxyPassReverse / http://0.0.0.0:8080/

210

</VirtualHost>

211

```

212

213

### Apache on Debian, Ubuntu and derivates

214

215

- Install apache2 via `apt install -y apache2`

216

- Enable proxy modules via `a2enmod proxy proxy_http`

217

- Create the `otterwiki.conf` config file in `/etc/apache2/site-available/`

218

- Enable the site via `a2ensite otterwiki`

219

- Restart apache2 `systemctl restart apache2`

220

- Open <http://wiki.domain.tld> in your browser

221

- Check `journalctl -xeu apache2.service` and `/var/log/apache2/error.log` for error messages.

222

223

### Apache on RHEL, CentOS, Rocky and derivates

224

225

- Install apache2 via `dnf install httpd`

226

- Start apache2 and enable at boot: `sudo systemctl enable --now httpd` 

227

- Create the `otterwiki.conf` config file in `/etc/httpd/conf.d/`

228

- With SELinux enabled, make sure httpd can connect using `setsebool -P httpd_can_network_connect on`

229

- Restart apache2 via `systemctl restart httpd`

230

- Open <http://wiki.domain.tld> in your browser

231

- Check `journalctl -xeu httpd.service` and `/var/log/httpd/error_log` for error messages.

232

233

## Caddy

234

235

[Caddy](https://caddyserver.com/) is an open source webserver with a very light configuration that makes a fine reverse proxy.

236

237

After [installing](https://caddyserver.com/docs/install) caddy, configure `/etc/caddy/Caddyfile` with e.g.

238

239

```

240

domain.tld {

241

reverse_proxy localhost:8080

242

}

243

```

244

245

With a server accessible from the internet, `domain.tld` beeing a proper domain name with A/AAAA DNS records pointing to the server, caddy will [automatically](https://caddyserver.com/docs/automatic-https) serve HTTPS.