From ef1953ad62e089fc47baf69b89af2ee6a6453174 Mon Sep 17 00:00:00 2001
From: Thomas Birke <quafzi@netextreme.de>
Date: Sat, 29 Aug 2026 16:22:52 +0200
Subject: [PATCH] Improve README: docker-compose installation and WP reference
 syntax

- Replace vague Docker paragraph with concrete docker-compose
  instructions: custom Dockerfile, docker-compose snippet, build/migrate
  commands
- Update referencing section to reflect that semantic IDs (PROJ-42)
  no longer require the OP# prefix
---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 56 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index ae30f61..0fca598 100644
--- a/README.md
+++ b/README.md
@@ -26,8 +26,9 @@ When a pull request in Gitea references an OpenProject work package (via a URL o
 
 In a pull request title, description, or comment, reference a work package using:
 
-- A full URL: `https://openproject.example.com/work_packages/42`
-- A short reference: `OP#42` or `OP#PROJ-42`
+- Its semantic ID: `KS-10`, `PROJ-42` — matched automatically, no prefix needed
+- A prefixed numeric ID: `OP#42` — prefix required to avoid collision with Gitea issue numbers
+- A full OpenProject URL: `https://openproject.example.com/work_packages/42`
 
 Multiple references in the same text are all picked up.
 
@@ -57,9 +58,60 @@ openproject config:set RECOMPILE_ANGULAR_ASSETS=true
 sudo openproject configure
 ```
 
-### Docker installation
+### Docker / docker-compose installation
 
-Follow the [OpenProject Docker plugin guide](https://www.openproject.org/docs/installation-and-operations/installation/docker/#openproject-plugins). Add the gem to your custom Gemfile and rebuild the image.
+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.
+
+#### 1. Create a `Dockerfile` that extends the official image
+
+```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
+
+# 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" \
+    > /app/Gemfile.plugins && \
+    cd /app && \
+    bundle install --without development test && \
+    RAILS_ENV=production bundle exec rake \
+      openproject:plugins:register_frontend \
+      assets:precompile
+
+USER app
+```
+
+#### 2. Build and reference the image in `docker-compose.yml`
+
+```yaml
+services:
+  web:
+    build:
+      context: .        # directory containing your Dockerfile and the plugin source
+      dockerfile: Dockerfile
+    # … rest of your existing web service config
+  worker:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    # … rest of your existing worker service config
+```
+
+#### 3. Build and restart
+
+```shell
+docker compose build
+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.
 
 ### Manual / monorepo installation