From 56006345746b97f3b8d267eec4c2cbbff137d4d5 Mon Sep 17 00:00:00 2001
From: Lain Soykaf <lain@lain.com>
Date: Wed, 31 Dec 2025 18:52:14 +0400
Subject: [PATCH] Installation: Add Release-Via-Docker option

---
 docs/installation/otp_en.md                   |  3 +
 docs/installation/release_to_docker_en.md     | 61 +++++++++++++++++
 installation/release-to-docker/Dockerfile     | 24 +++++++
 installation/release-to-docker/README.md      | 66 +++++++++++++++++++
 .../release-to-docker/docker-compose.yml      | 22 +++++++
 .../pleroma-host-release-entrypoint.sh        | 19 ++++++
 .../release-to-docker/pleroma.service         | 16 +++++
 7 files changed, 211 insertions(+)
 create mode 100644 docs/installation/release_to_docker_en.md
 create mode 100644 installation/release-to-docker/Dockerfile
 create mode 100644 installation/release-to-docker/README.md
 create mode 100644 installation/release-to-docker/docker-compose.yml
 create mode 100644 installation/release-to-docker/pleroma-host-release-entrypoint.sh
 create mode 100644 installation/release-to-docker/pleroma.service

diff --git a/docs/installation/otp_en.md b/docs/installation/otp_en.md
index 86efa27f8..123dccf3a 100644
--- 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
new file mode 100644
index 000000000..a1fd165ac
--- /dev/null
+++ 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
new file mode 100644
index 000000000..ddff4570d
--- /dev/null
+++ 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
new file mode 100644
index 000000000..4129bd94b
--- /dev/null
+++ 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
new file mode 100644
index 000000000..043803241
--- /dev/null
+++ 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:rw
diff --git a/installation/release-to-docker/pleroma-host-release-entrypoint.sh b/installation/release-to-docker/pleroma-host-release-entrypoint.sh
new file mode 100644
index 000000000..b9c035678
--- /dev/null
+++ 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
new file mode 100644
index 000000000..d3833363c
--- /dev/null
+++ 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