From 299a20fb715d87a84a6b4e431c95adfe71335bdd Mon Sep 17 00:00:00 2001 From: Jeder Date: Wed, 3 Jan 2024 22:57:10 +0100 Subject: [PATCH] [docs] Add podman (quadlet/systemd) installation guide Co-authored-by: Jeder Co-committed-by: Jeder --- .../Podman (quadlet)/iceshrimp-db.container | 14 +++ .../iceshrimp-redis.container | 14 +++ .../Podman (quadlet)/iceshrimp-web.container | 16 ++++ .../Podman (quadlet)/iceshrimp.network | 1 + .../Podman (quadlet)/volume-dir-creation.sh | 24 +++++ docs/podman-install.md | 88 +++++++++++++++++++ 6 files changed, 157 insertions(+) create mode 100644 docs/examples/Podman (quadlet)/iceshrimp-db.container create mode 100644 docs/examples/Podman (quadlet)/iceshrimp-redis.container create mode 100644 docs/examples/Podman (quadlet)/iceshrimp-web.container create mode 100644 docs/examples/Podman (quadlet)/iceshrimp.network create mode 100755 docs/examples/Podman (quadlet)/volume-dir-creation.sh create mode 100644 docs/podman-install.md diff --git a/docs/examples/Podman (quadlet)/iceshrimp-db.container b/docs/examples/Podman (quadlet)/iceshrimp-db.container new file mode 100644 index 000000000..b5a351540 --- /dev/null +++ b/docs/examples/Podman (quadlet)/iceshrimp-db.container @@ -0,0 +1,14 @@ +[Unit] +Description=Iceshrimp PostgreSQL container +[Container] +Image=docker.io/postgres:15-alpine +ContainerName=iceshrimp_db +HostName=db +Network=iceshrimp.network +EnvironmentFile=%h/services/iceshrimp/.config/docker.env +Volume=%h/services/iceshrimp/db:/var/lib/postgresql/data:Z +[Service] +Restart=on-failure +TimeoutStartSec=900 +[Install] +WantedBy=iceshrimp-web.service diff --git a/docs/examples/Podman (quadlet)/iceshrimp-redis.container b/docs/examples/Podman (quadlet)/iceshrimp-redis.container new file mode 100644 index 000000000..38e5015d0 --- /dev/null +++ b/docs/examples/Podman (quadlet)/iceshrimp-redis.container @@ -0,0 +1,14 @@ +[Unit] +Description=Iceshrimp Redis container +[Container] +Image=docker.io/redis:7.0-alpine +ContainerName=iceshrimp_redis +HostName=redis +Network=iceshrimp.network +Volume=%h/services/iceshrimp/redis:/data:Z +[Service] +Restart=on-failure +TimeoutStartSec=900 +[Install] +WantedBy=iceshrimp-web.service + diff --git a/docs/examples/Podman (quadlet)/iceshrimp-web.container b/docs/examples/Podman (quadlet)/iceshrimp-web.container new file mode 100644 index 000000000..091c4a1ea --- /dev/null +++ b/docs/examples/Podman (quadlet)/iceshrimp-web.container @@ -0,0 +1,16 @@ +[Unit] +Description=Iceshrimp container +[Container] +Image=iceshrimp.dev/iceshrimp/iceshrimp:latest +ContainerName=iceshrimp_web +HostName=web +PublishPort=3000:3000 +Network=iceshrimp.network +Environment=NODE_ENV=production +Volume=%h/services/iceshrimp/files:/iceshrimp/files:z +Volume=%h/services/iceshrimp/.config:/iceshrimp/.config:ro,z +[Service] +Restart=on-failure +TimeoutStartSec=900 +[Install] +WantedBy=multi-user.target default.target diff --git a/docs/examples/Podman (quadlet)/iceshrimp.network b/docs/examples/Podman (quadlet)/iceshrimp.network new file mode 100644 index 000000000..264f70a03 --- /dev/null +++ b/docs/examples/Podman (quadlet)/iceshrimp.network @@ -0,0 +1 @@ +[Network] diff --git a/docs/examples/Podman (quadlet)/volume-dir-creation.sh b/docs/examples/Podman (quadlet)/volume-dir-creation.sh new file mode 100755 index 000000000..d0877f987 --- /dev/null +++ b/docs/examples/Podman (quadlet)/volume-dir-creation.sh @@ -0,0 +1,24 @@ +#!/bin/bash +if [ -d $HOME/.config/containers/systemd ]; then + mkdir -pv $(grep -F "Volume=" $HOME/.config/containers/systemd/iceshrimp-*.container | sed "s|%h|$HOME|g" | cut -d= -f2 | cut -d: -f1); + + db_env=$(grep -F "EnvironmentFile=" $HOME/.config/containers/systemd/iceshrimp-db.container | sed "s|%h|$HOME|g" | cut -d= -f2) + config_dir=$(grep -F ":/iceshrimp/.config" $HOME/.config/containers/systemd/iceshrimp-web.container | sed "s|%h|$HOME|g" | cut -d= -f2 | cut -d: -f1) + + if [ ! -f $config_dir/docker_example.env ]; then + wget -O $db_env \ + https://iceshrimp.dev/iceshrimp/iceshrimp/raw/branch/dev/.config/docker_example.env; + else + cp -v $config_dir/docker_example.env $db_env; + fi + + if [ ! -f $config_dir/example-docker.yml ]; then + wget -O $config_dir/default.yml \ + https://iceshrimp.dev/iceshrimp/iceshrimp/raw/branch/dev/.config/example-docker.yml; + else + cp $config_dir/example-docker.yml $config_dir/default.yml + fi +else + echo "No $HOME/.config/containers/systemd found" + exit 1 +fi diff --git a/docs/podman-install.md b/docs/podman-install.md new file mode 100644 index 000000000..068d08af2 --- /dev/null +++ b/docs/podman-install.md @@ -0,0 +1,88 @@ +# Installing Iceshrimp using Podman and Quadlet +Quadlet is a feature of Podman that is kind of like Docker Compose, but is better integrated with systemd, just like whole Podman. + +## Requirements +- Podman 4.4+ with aardvark +- Git with LFS installed (if building your own images) + +## Preparations + +### Getting needed files + +If you want to use prebuilt images: + +```sh +GIT_LFS_SKIP_SMUDGE=1 git clone https://iceshrimp.dev/iceshrimp/iceshrimp.git --depth=1 +cp "iceshrimp/docs/examples/Podman (quadlet)" $HOME/.config/containers/systemd +``` + +Tweak quadlet files and change the image tag in `$HOME/.config/containers/systemd/iceshrimp-web.container` from `latest` to `dev` or `pre` if desired, and run `docs/examples/Podman\ \(quadlet\)/volume-dir-creation.sh`. + +If you want to build your own images: + +```sh +git lfs install +git clone https://iceshrimp.dev/iceshrimp/iceshrimp.git +cp "iceshrimp/docs/examples/Podman (quadlet)" $HOME/.config/containers/systemd + +``` + +Tweak quadlet files if needed, change content of `Image:` line in `$HOME/.config/containers/systemd/iceshrimp-web.container` to `Image: localhost/iceshrimp/iceshrimp:latest`, and run `docs/examples/Podman\ \(quadlet\)/volume-dir-creation.sh`. + +### .config + +Edit `.config/docker.env` and fill it with the database credentials you want. +Edit `.config/default.yml` and: + +- Replace example database credentials with the ones you entered in `.config/docker.env` +- Change other configuration + +## Installation and first start + +Choose a method, whether you chose to build the image yourself or not. + +### Pulling the image + +```sh +podman pull $(grep -F "Image=" $HOME/.config/containers/systemd/iceshrimp-web.container | cut -d= -f2) +systemctl --user start iceshrimp-web.service +``` + +### Building the image + +Enter Iceshrimp repo and run: + +```sh +podman build . -t $(grep -F "Image=" $HOME/.config/containers/systemd/iceshrimp-web.container | cut -d= -f2) --ulimit nofile=16384:16384 +systemctl --user start iceshrimp-web.service +``` + +## Starting Iceshrimp automatically + +Run `sudo loginctl enable-linger [user]` and Iceshrimp will start automatically on boot. You don't need to, and in fact [cannot enable Podman-generated systemd services](https://man.archlinux.org/man/extra/podman/podman-systemd.unit.5.en#Enabling_unit_files). + +## Updating Iceshrimp + +### Pulling the image + +```sh +podman pull $(grep -F "Image=" $HOME/.config/containers/systemd/iceshrimp-web.container | cut -d= -f2) +systemctl --user restart iceshrimp-web.service +``` + +### Building the image + +```sh +## Run git stash commands only if you have uncommitted changes +git stash +git pull +git stash pop +podman build . -t $(grep -F "Image=" $HOME/.config/containers/systemd/iceshrimp-web.container | cut -d= -f2) --ulimit nofile=16384:16384 +systemctl --user restart iceshrimp-web.service +``` + +## Post-install + +If you are running Iceshrimp on a system with more than one CPU thread, you might want to set the `clusterLimit` config option to about half of your thread count, depending on your system configuration. Please note that each worker requires around 10 PostgreSQL connections, so be sure to set `max_connections` appropriately. To do this, change `max_connections=n` line in `db/postgresql.conf`, with `n` being `(10 * no_workers) + 10`, and run `systemctl --user restart iceshrimp-db iceshrimp-web`. + +See also [post-install](post-install.md). \ No newline at end of file