From 345765e21fd443ad758cfbdd21dcc779969c4cf1 Mon Sep 17 00:00:00 2001
From: Rik Huijzer <github@huijzer.xyz>
Date: Thu, 7 Mar 2024 17:04:47 +0100
Subject: [PATCH] Add rootless installation instructions

---
 docs/admin/installation-docker.md | 82 +++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/docs/admin/installation-docker.md b/docs/admin/installation-docker.md
index c438d75c..77acefc4 100644
--- a/docs/admin/installation-docker.md
+++ b/docs/admin/installation-docker.md
@@ -67,6 +67,88 @@ ENABLE_PUSH_CREATE_USER = true
 
 > **NOTE:** in case you are in a selinux environment check the audit logs if you are having issues with containers.
 
+## Rootless
+
+Forgejo also supports a rootless Docker image.
+With this image, the Docker container can run as an unprivileged user, which means that an attacker will not have root privileges on the server even when they break out of the container.
+
+This configuration is slightly more involved because we need to prepare our data folders.
+To do so, we create a `data` folder with permissions for the user with `UID` and `GID` 1000.
+This is the user which should **not** have root privileges.
+
+```sh
+#!/usr/bin/env bash
+
+set -e
+
+mkdir -p work
+mkdir -p work/data
+
+chown -R 1000:1000 work/data
+chmod 775 work/data
+chmod g+s work/data
+```
+
+```yaml
+version: '3'
+
+networks:
+  forgejo:
+    external: false
+
+services:
+  gitea:
+    image: 'codeberg.org/forgejo/forgejo:1.21-rootless'
+    container_name: 'forgejo'
+    environment:
+      USER_UID: '1000'
+      USER_GID: '1000'
+      FORGEJO_WORK_DIR: '/var/lib/forge'
+    user: '1000:1000'
+    networks:
+      - forgejo
+    ports:
+      - '3000:3000'
+      - '222:22'
+    volumes:
+      - ./forgejo:/data:rw'
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+      # Right side of this mount depends on the `FORGEJO_WORK_DIR` var above.
+      - ./work:/var/lib/forge:rw
+    logging:
+      driver: 'json-file'
+      options:
+        max-size: '10m'
+        max-file: '10'
+    restart: 'unless-stopped'
+```
+
+To also mount a locally defined `app.ini`, add
+
+```yaml
+      - ./app.ini:/etc/gitea/app.ini
+```
+
+to `volumes`.
+Next, run this with
+
+```sh
+docker compose up
+```
+
+To, for example, add an admin user from the command line, use:
+
+```sh
+docker exec -ti forgejo /bin/bash
+```
+
+and
+
+```sh
+forgejo admin user create --username <USERNAME> --password <PASSWORD> --email <EMAIL> --admin
+```
+
 ## Databases
 
 In the following each database is shown as part of a `docker-compose` example file, with a `diff like` presentation that highlights additions to the example above.