commit: db48aa5cdb31772d738f31cfcd591c2d35ec5551 parent 3b99bbd9550f67698bfa294ee18a17f337510b81 Author: Lain Soykaf <lain@lain.com> Date: Wed, 31 Dec 2025 18:52:14 +0400 Installation: Add Release-Via-Docker optionDiffstat:
| M | docs/installation/otp_en.md | 3 | +++ |
| A | docs/installation/release_to_docker_en.md | 61 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | installation/release-to-docker/Dockerfile | 24 | ++++++++++++++++++++++++ |
| A | installation/release-to-docker/README.md | 66 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | installation/release-to-docker/docker-compose.yml | 22 | ++++++++++++++++++++++ |
| A | installation/release-to-docker/pleroma-host-release-entrypoint.sh | 19 | +++++++++++++++++++ |
| A | installation/release-to-docker/pleroma.service | 16 | ++++++++++++++++ |
7 files changed, 211 insertions(+), 0 deletions(-)diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md@@ -13,6 +13,9 @@ You will be running commands as root. If you aren't root already, please elevate Similarly to other binaries, OTP releases tend to be only compatible with the distro they are built on, as such this guide focuses only on Debian/Ubuntu and Alpine. +!!! note + If you get `GLIBC_... not found` errors on Debian/Ubuntu, you can run the OTP release from `/opt/pleroma` inside a newer distro container without upgrading the host. See [`release_to_docker_en.md`](release_to_docker_en.md). + ### Detecting flavour Paste the following into the shell:diff --git a/docs/installation/release_to_docker_en.md b/docs/installation/release_to_docker_en.md@@ -0,0 +1,61 @@ +# Running OTP releases via Docker (glibc shim) + +Pleroma OTP releases are built on specific distros. If your host OS is older than +the build environment, you may hit runtime linker errors such as: + +``` +/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found +``` + +If you don't want to upgrade your host OS, you can run the existing OTP release +from `/opt/pleroma` inside an Ubuntu 24.04 container while keeping your existing +host config and data directories. + +This approach uses a small "shim" container image to provide a newer `glibc`. +It is **not** the official Pleroma Docker image. + +## Requirements + +- Docker Engine + the Docker Compose plugin on the host +- Root access (or equivalent access to the Docker socket) +- Existing OTP release in `/opt/pleroma` +- Existing config in `/etc/pleroma` and data in `/var/lib/pleroma` + +## Setup + +1. Copy the provided templates: + + ```sh + mkdir -p /etc/pleroma/container + cp -a /opt/pleroma/installation/release-to-docker/* /etc/pleroma/container/ + ``` + +2. Build the shim image: + + ```sh + cd /etc/pleroma/container + docker compose build + ``` + +3. Replace your systemd unit: + + ```sh + cp /etc/pleroma/container/pleroma.service /etc/systemd/system/pleroma.service + systemctl daemon-reload + systemctl enable --now pleroma + journalctl -u pleroma -f + ``` + +## Running migrations / `pleroma_ctl` + +Migrations are run automatically by default when the container starts. You can +disable this by setting `PLEROMA_RUN_MIGRATIONS=0` in +`/etc/pleroma/container/docker-compose.yml`. + +To run admin commands inside the container: + +```sh +cd /etc/pleroma/container +docker compose exec pleroma /opt/pleroma/bin/pleroma_ctl status +docker compose run --rm --no-deps pleroma /opt/pleroma/bin/pleroma_ctl migrate +```diff --git a/installation/release-to-docker/Dockerfile b/installation/release-to-docker/Dockerfile@@ -0,0 +1,24 @@ +FROM ubuntu:24.04 + +ENV DEBIAN_FRONTEND=noninteractive \ + LANG=C.UTF-8 \ + LC_ALL=C.UTF-8 + +RUN apt-get update && apt-get install -y --no-install-recommends \ + ca-certificates \ + gosu \ + libstdc++6 \ + libncurses6 libncursesw6 \ + openssl libssl3 \ + libmagic1t64 file \ + postgresql-client \ + ffmpeg imagemagick libimage-exiftool-perl \ + libvips42t64 \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /opt/pleroma + +COPY pleroma-host-release-entrypoint.sh /usr/local/bin/pleroma-host-release-entrypoint.sh +RUN chmod +x /usr/local/bin/pleroma-host-release-entrypoint.sh +ENTRYPOINT ["/usr/local/bin/pleroma-host-release-entrypoint.sh"] +CMD ["/opt/pleroma/bin/pleroma", "start"]diff --git a/installation/release-to-docker/README.md b/installation/release-to-docker/README.md@@ -0,0 +1,66 @@ +# Run OTP releases on older glibc using Docker + +Pleroma OTP releases are built on specific distros and may require a newer `glibc` +than your host has. A typical failure looks like: + +``` +... /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.38' not found ... +``` + +If you don't want to upgrade your host OS, you can run the existing OTP release +from `/opt/pleroma` inside an Ubuntu 24.04 container while keeping your existing +host paths (`/etc/pleroma`, `/var/lib/pleroma`, etc.). + +This folder provides a "shim" container + systemd unit. It is **not** the Pleroma +Docker image. + +## What this does + +- Builds a small Ubuntu 24.04 image with runtime libs (including newer `glibc`). +- Mounts your existing host release at `/opt/pleroma` into the container. +- Runs as the same UID/GID that owns `/opt/pleroma` on the host (via `gosu`). +- Optionally runs migrations automatically on container start. +- Uses `network_mode: host` so your existing config that talks to `localhost` + keeps working. + +## Setup (Debian/Ubuntu host) + +1. Install Docker Engine + the Docker Compose plugin. +2. Copy these files to a stable location (example: `/etc/pleroma/container`): + + ``` + mkdir -p /etc/pleroma/container + cp -a /opt/pleroma/installation/release-to-docker/* /etc/pleroma/container/ + ``` + +3. Build the shim image: + + ``` + cd /etc/pleroma/container + docker compose build + ``` + +4. Replace your systemd unit: + + ``` + cp /etc/pleroma/container/pleroma.service /etc/systemd/system/pleroma.service + systemctl daemon-reload + systemctl enable --now pleroma + journalctl -u pleroma -f + ``` + +## Running `pleroma_ctl` + +Since the host binary may not run on older `glibc`, run admin commands inside the +container: + +``` +cd /etc/pleroma/container +docker compose exec pleroma /opt/pleroma/bin/pleroma_ctl status +docker compose run --rm --no-deps pleroma /opt/pleroma/bin/pleroma_ctl migrate +``` + +## Configuration notes + +- Migrations run automatically by default. + - Set `PLEROMA_RUN_MIGRATIONS=0` in `docker-compose.yml` to disable.diff --git a/installation/release-to-docker/docker-compose.yml b/installation/release-to-docker/docker-compose.yml@@ -0,0 +1,22 @@ +services: + pleroma: + build: + context: . + dockerfile: Dockerfile + image: pleroma-host-release-wrapper:ubuntu24 + init: true + network_mode: host + restart: unless-stopped + environment: + HOME: /opt/pleroma + LANG: C.UTF-8 + LC_ALL: C.UTF-8 + ELIXIR_ERL_OPTIONS: "+fnu" + # Set to 0 to skip running migrations on container start. + PLEROMA_RUN_MIGRATIONS: "1" + volumes: + # Existing OTP release installation (host) + - /opt/pleroma:/opt/pleroma:rw + # Existing config + uploads + static (host) + - /etc/pleroma:/etc/pleroma:rw + - /var/lib/pleroma:/var/lib/pleroma:rwdiff --git a/installation/release-to-docker/pleroma-host-release-entrypoint.sh b/installation/release-to-docker/pleroma-host-release-entrypoint.sh@@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -euo pipefail + +uid="${PLEROMA_UID:-}" +gid="${PLEROMA_GID:-}" + +if [[ -z "${uid}" || -z "${gid}" ]]; then + uid="$(stat -c '%u' /opt/pleroma)" + gid="$(stat -c '%g' /opt/pleroma)" +fi + +export HOME="${HOME:-/opt/pleroma}" + +if [[ "${PLEROMA_RUN_MIGRATIONS:-1}" != "0" && "${1:-}" == "/opt/pleroma/bin/pleroma" && "${2:-}" == "start" ]]; then + echo "Running migrations..." + gosu "${uid}:${gid}" /opt/pleroma/bin/pleroma_ctl migrate +fi + +exec gosu "${uid}:${gid}" "$@"diff --git a/installation/release-to-docker/pleroma.service b/installation/release-to-docker/pleroma.service@@ -0,0 +1,16 @@ +[Unit] +Description=Pleroma social network (OTP release via Docker glibc shim) +After=network.target docker.service postgresql.service nginx.service +Requires=docker.service + +[Service] +Type=simple +WorkingDirectory=/etc/pleroma/container +ExecStart=/usr/bin/docker compose up --build --remove-orphans +ExecStop=/usr/bin/docker compose down +Restart=on-failure +RestartSec=5s +TimeoutStartSec=0 + +[Install] +WantedBy=multi-user.target