From b6f547742088f66ae41e4830ae528d6100be0c7e Mon Sep 17 00:00:00 2001 From: enoch85 Date: Sat, 19 Sep 2026 14:50:39 +0000 Subject: [PATCH] docs: fix install example indentation, add Podman, nest platform tabs Maintainerr/Maintainerr#3752 --- docs/Collections.md | 2 +- docs/Installation.mdx | 222 ++++++++++++++++++++++++++++++------------ 2 files changed, 162 insertions(+), 62 deletions(-) diff --git a/docs/Collections.md b/docs/Collections.md index f4526ac33..61166c3ad 100644 --- a/docs/Collections.md +++ b/docs/Collections.md @@ -223,7 +223,7 @@ None of the *arr root folders are visible to Maintainerr for 'Some Movie'; mount If you see this message, check that the host path and the container path are both identical across your Radarr/Sonarr and Maintainerr service definitions. ::: -For a Compose example with the optional media-library bind mount, see the [Docker installation instructions](./Installation.mdx#docker). The media-library `source` and `target` must use the same container path that Radarr or Sonarr reports for its root folder. +For a Compose example with the optional media-library bind mount, see the [Docker installation instructions](./Installation.mdx#install). The media-library `source` and `target` must use the same container path that Radarr or Sonarr reports for its root folder. ### Cleanup safety gates diff --git a/docs/Installation.mdx b/docs/Installation.mdx index 14b5f83f0..74387d19d 100644 --- a/docs/Installation.mdx +++ b/docs/Installation.mdx @@ -10,6 +10,53 @@ import TabItem from "@theme/TabItem"; import Details from "@theme/Details"; import AnnotatedCodeBlock from "@site/src/components/AnnotatedCodeBlock"; +export const composeExample = `services: + maintainerr: + image: ghcr.io/maintainerr/maintainerr:latest + user: 1000:1000 + volumes: + - type: bind + source: + target: /opt/data + - type: bind + source: /data/media # optional: only for leftover-folder cleanup + target: /data/media + environment: + - TZ=Europe/Brussels + ports: + - 6246:6246 + restart: unless-stopped`; + +export const runExample = `docker run -d \\ + --name maintainerr \\ + -e TZ=Europe/Brussels \\ + -v :/opt/data \\ + -v /data/media:/data/media \\ + -u 1000:1000 \\ + -p 6246:6246 \\ + --restart unless-stopped \\ + ghcr.io/maintainerr/maintainerr:latest`; + +export const quadletExample = `[Unit] +Description=Maintainerr + +[Container] +Image=ghcr.io/maintainerr/maintainerr:latest +ContainerName=maintainerr +UserNS=keep-id:uid=1000,gid=1000 +Volume=%h/maintainerr/data:/opt/data:Z +#Volume=/data/media:/data/media:Z +Environment=TZ=Europe/Brussels +PublishPort=6246:6246 +#AutoUpdate=registry + +[Service] +Restart=always +TimeoutStartSec=900 + +[Install] +WantedBy=default.target`; + Docker is Maintainerr's supported method of installation. Images for amd64 & arm64 are available under `maintainerr/maintainerr` and `ghcr.io/maintainerr/maintainerr`. @@ -23,33 +70,20 @@ Maintainerr uses the configured `user:group` as its runtime user inside the cont If you do not set one explicitly, the default `UID:GID` is `1000:1000`, so make sure your host data directory is read/writeable by that UID:GID. If needed, update it with `chown -R 1000:1000 /opt/data`. ::: -## Docker +## Install -Compose is recommended for most installs. Choose the Docker example that matches your workflow. +Pick your platform, then the step you need. Compose is recommended for most Docker installs. - - + + + + Define the Maintainerr service in your docker-compose.yml as follows: - target: /opt/data - - type: bind - source: /data/media # optional: only for leftover-folder cleanup - target: /data/media - environment: - - TZ=Europe/Brussels - ports: - - 6246:6246 - restart: unless-stopped`} + code={composeExample} annotations={[ { line: 3, @@ -84,22 +118,14 @@ Then, while in the directory where your docker-compose file exists, start all se docker compose up -d ``` - - + + Run Maintainerr with the following command: :/opt/data \\ - -v /data/media:/data/media \\ - -u 1000:1000 \\ - -p 6246:6246 \\ - --restart unless-stopped \\ - ghcr.io/maintainerr/maintainerr:latest`} + code={runExample} annotations={[ { line: 4, @@ -127,28 +153,8 @@ Run Maintainerr with the following command: ]} /> - - - -The optional media-library bind mount is required for [leftover-folder cleanup](./Collections.md#leftover-folder-cleanup). Use the same container path that Radarr or Sonarr reports for its root folder, and make sure the configured `user:group` can write to it. - -
- -While the development version contains all of the latest features and bug -fixes, there is a chance things will break. By using a development version -you must be willing to report any issues you come across, to the development -team, and provide as much information as possible to help resolve the issue. - -Changing from a development version to a stable version is not supported. - -- `ghcr.io/maintainerr/maintainerr:development` for the development branch. -- `maintainerr/maintainerr:development` for the Docker Hub development image. - -
- -### Updating - -#### Update to the latest version with Compose + + If you installed Maintainerr with Compose, navigate to the directory containing your `docker-compose.yml` and run: @@ -159,24 +165,95 @@ docker compose up -d This updates Maintainerr using the image tag defined in your Compose file. -#### Stop and remove an existing container - -Use these commands if you need to stop and remove a container that was started manually with `docker run`: +If you started the container manually with `docker run`, pull the new image, remove the old container, then run the same `docker run` command again. Pulling a new image by itself does not update an existing container. ```bash +docker pull ghcr.io/maintainerr/maintainerr:latest docker stop maintainerr docker rm -f maintainerr ``` -#### Pull the latest image only + + + + + + + -Use this command if you only want to download the latest image. Pulling a new image by itself does not update an existing container. +Save the unit below as `~/.config/containers/systemd/maintainerr.container`. Quadlet does not allow comments after a value, so each optional line is commented out as a whole. + + + +Create the data directory and start the unit: ```bash -docker pull ghcr.io/maintainerr/maintainerr +mkdir -p ~/maintainerr/data +systemctl --user daemon-reload +systemctl --user start maintainerr +loginctl enable-linger "$USER" # keeps it running while you are logged out ``` -## Kubernetes +For a rootful install, put the file in `/etc/containers/systemd/` instead, replace `UserNS=` with `User=1000` and `Group=1000` (the data directory must then be owned by `1000:1000`), use an absolute data path, set `WantedBy=multi-user.target`, and run `systemctl` without `--user`. + + + + +Pull the new image and restart the unit: + +```bash +podman pull ghcr.io/maintainerr/maintainerr:latest +systemctl --user restart maintainerr +``` + +With `AutoUpdate=registry` enabled in the unit, `podman auto-update` does both steps for you. + + + + + + + + Use the example below as a starting point for a single-instance Maintainerr deployment with a Service and persistent storage claim. @@ -251,7 +328,8 @@ spec: storage: 1Gi ``` -### Updating + + To update your Kubernetes deployment to the latest Maintainerr image, update the image tag in your manifest (or leave it as `latest`) and re-apply: @@ -267,6 +345,28 @@ kubectl apply -f maintainerr-deployment.yaml Kubernetes will perform a rolling update, replacing the old pod with one running the new image. + + + + + + +The optional media-library bind mount is required for [leftover-folder cleanup](./Collections.md#leftover-folder-cleanup). Use the same container path that Radarr or Sonarr reports for its root folder, and make sure the configured `user:group` can write to it. + +
+ +While the development version contains all of the latest features and bug +fixes, there is a chance things will break. By using a development version +you must be willing to report any issues you come across, to the development +team, and provide as much information as possible to help resolve the issue. + +Changing from a development version to a stable version is not supported. + +- `ghcr.io/maintainerr/maintainerr:development` for the development branch. +- `maintainerr/maintainerr:development` for the Docker Hub development image. + +
+ ## Health checks Maintainerr ships lightweight health endpoints under `/api/health` for orchestration probes and uptime monitoring. They are prefixed with `BASE_PATH` when you serve Maintainerr from a subfolder.