From 8dcb4992893eb370ca504db4d3fcadf4573fc4e1 Mon Sep 17 00:00:00 2001
From: Thomas Birke <quafzi@netextreme.de>
Date: Sat, 29 Aug 2026 16:58:35 +0200
Subject: [PATCH] Use docker-compose.override.yml pattern for Docker
 installation

Editing docker-compose.yml directly is overwritten on every pull.
The correct approach is a separate Dockerfile.gitea (owned by the
operator) referenced from docker-compose.override.yml, which is
never touched by upstream updates.
---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 39 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 0fca598..6ae96d9 100644
--- a/README.md
+++ b/README.md
@@ -62,20 +62,33 @@ sudo openproject configure
 
 The official OpenProject Docker image bakes all gems and frontend assets in at
 build time, so installing a third-party plugin requires building a custom image.
+The `docker-compose.yml` provided by OpenProject is overwritten on every update,
+so all local changes go into `docker-compose.override.yml` and a separate
+`Dockerfile` that you own.
 
-#### 1. Create a `Dockerfile` that extends the official image
+#### 1. Clone the plugin
+
+```shell
+git clone https://github.com/your-org/openproject-gitea-integration.git \
+  openproject-gitea_integration
+```
+
+Place it anywhere convenient — this guide assumes it sits next to your
+`docker-compose.yml`.
+
+#### 2. Create `Dockerfile.gitea`
 
 ```dockerfile
 FROM openproject/openproject:15
 
-# Switch to root to install build tools and re-bundle
 USER root
 
-# Copy the plugin into the modules directory
-COPY --chown=app:app . /app/modules/gitea_integration
+# Copy the plugin source into the image
+COPY --chown=app:app openproject-gitea_integration \
+     /app/modules/gitea_integration
 
-# Add the gem to a custom Gemfile that OpenProject will merge
-RUN echo "group :opf_plugins do\n  gem 'openproject-gitea_integration', path: 'modules/gitea_integration'\nend" \
+# Register the gem and recompile assets
+RUN echo 'group :opf_plugins do\n  gem "openproject-gitea_integration", path: "modules/gitea_integration"\nend' \
     > /app/Gemfile.plugins && \
     cd /app && \
     bundle install --without development test && \
@@ -86,23 +99,28 @@ RUN echo "group :opf_plugins do\n  gem 'openproject-gitea_integration', path: 'm
 USER app
 ```
 
-#### 2. Build and reference the image in `docker-compose.yml`
+#### 3. Create `docker-compose.override.yml`
+
+This file is never touched by OpenProject updates. Point both `web` and
+`worker` at your custom image — they must use the same image so the plugin is
+loaded in both processes.
 
 ```yaml
 services:
   web:
     build:
-      context: .        # directory containing your Dockerfile and the plugin source
-      dockerfile: Dockerfile
-    # … rest of your existing web service config
+      context: .
+      dockerfile: Dockerfile.gitea
+    image: openproject-with-gitea:latest
+
   worker:
     build:
       context: .
-      dockerfile: Dockerfile
-    # … rest of your existing worker service config
+      dockerfile: Dockerfile.gitea
+    image: openproject-with-gitea:latest
 ```
 
-#### 3. Build and restart
+#### 4. Build and start
 
 ```shell
 docker compose build
@@ -110,8 +128,14 @@ docker compose up -d
 docker compose exec web bundle exec rails db:migrate
 ```
 
-> **Note:** Every time you update the plugin you need to rebuild the image
-> (`docker compose build --no-cache`) and restart the stack.
+#### Updating the plugin
+
+```shell
+cd openproject-gitea_integration && git pull && cd ..
+docker compose build --no-cache
+docker compose up -d
+docker compose exec web bundle exec rails db:migrate
+```
 
 ### Manual / monorepo installation