Blame

669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
1
# Upgrade
2
3
This pages describes how to upgrade An Otter Wiki to the latest version. The project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
4
5
> [!IMPORTANT]
6
> **Minor version upgrades, e.g. from 2.x to 2.y are effortless.**
7
7be8a9 Ralph Thesen 2026-08-30 14:13:12
Explain image variant choice and why rollback is safe in upgrade guide
8
If a new version does not work as expected, you can just roll back to the version you previously used. This is safe: the preferences you set through the settings interface live in `/app-data/db.sqlite`, not in the image. Pulling an older tag restores the previous behaviour without losing your configuration.
669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
9
10
Check the [CHANGELOG](https://github.com/redimp/otterwiki/blob/main/CHANGELOG.md) for information about fixes and new feature of recent releases.
11
7be8a9 Ralph Thesen 2026-08-30 14:13:12
Explain image variant choice and why rollback is safe in upgrade guide
12
## Choosing the image variant
13
14
An Otter Wiki is published both as the full `redimp/otterwiki:2` image and the lighter `redimp/otterwiki:2-slim` variant, see [[the -slim image variant|Installation#the-slim-image-variant]] for the differences between them. The two are interchangeable, but mind the port when switching: the `-slim` image listens only on port 8080, while the full image listens on both port 80 and port 8080. A port mapping onto the container's port 8080, for example `-p 8080:8080`, therefore works with either variant. A mapping onto port 80, like `-p 8080:80`, works only with the full image, so change it to the container's port 8080 before switching to `-slim`.
15
669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
16
## docker cli
17
18
Make sure to collect the parameters you've used to create and run the container and start with cleaning up the existing container:
19
20
```bash
21
# stop the running container
22
docker stop otterwiki
23
# delete the container
3b6c36 Ralph Thesen 2026-08-30 13:33:35
Fix container name in the docker cli upgrade example
24
docker rm otterwiki
669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
25
```
26
27
Next step is fetching the new image via:
28
29
```bash
30
# pull the new image
31
docker pull redimp/otterwiki:2
32
```
33
34
and recreate the container, make sure to use the parameters you have used before, e.g.
35
36
```bash
37
# create and run the new container using the latest image
38
docker run --name otterwiki \
39
-p 8080:80 \
40
-v $PWD/app-data:/app-data \
41
redimp/otterwiki:2
42
```
43
44
## docker compose
45
46
To upgrade An Otter Wiki deployed via `docker compose`, find the folder where your `docker-compose.yaml` or `compose.yaml` lives and run
47
48
```bash
49
docker compose pull && docker compose up -d
50
```
51
ae8639 Ralph Thesen 2026-08-30 13:35:00
Fix typos in the upgrade guide
52
This will pull the latest image and recreate the container if necessary, so you can reduce the downtime to a minimum.
669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
53
54
## podman and podman-compose
55
56
Follow the process describe for `docker` and `docker compose` above.
57
58
## Kubernetes
59
60
When you deployed An Otter Wiki using the official [helm chart](https://github.com/redimp/otterwiki/tree/main/helm) configure the application with `--set image.pullPolicy=Always` and let the deployment do a rollout restart e.g.
61
62
```bash
63
kubectl rollout restart deployment \
64
--namespace=NAMESPACE \
65
--selector=app.kubernetes.io/name=otterwiki
66
```
67
68
## source version
69
70
To check out the latest release run:
71
```bash
72
# Update the repository information
73
git remote update origin
74
# Get the latest release tag
75
LATEST_RELEASE=$(git describe --tags $(git rev-list --tags --max-count=1))
76
# Create a new branch named like the latest release version.
77
git checkout -b $LATEST_RELEASE $LATEST_RELEASE
78
```
79
ae8639 Ralph Thesen 2026-08-30 13:35:00
Fix typos in the upgrade guide
80
When you installed An Otter Wiki in e.g. a virtual environment `venv` update the venv using:
669e20 Ralph Thesen 2025-07-09 21:25:16
Added Upgrade documentation
81
```
82
./venv/bin/pip install -U .
83
```
84
85
Restart the uwsgi server running the application, in case you are running it as an systemd service run a `systemctl restart otterwiki.service`.