docs: encourage community patches (#3794)

Hopefully this will provide a better guide on how to create patches.

optional-modifications/README.md

@@ -1,11 +1,10 @@
 # Optional Modifications
 
-Other than the default self-hosted Sentry installation, sometimes users
+While the default self-hosted Sentry installation is often sufficient, there are instances where leveraging existing infrastructure becomes a practical necessity, particularly for users with limited resources. This is where **patches**, or what can be understood as a **plugin system**, come into play.
-can leverage their existing infrastructure to help them with limited
+
-resources. "Patches", or you might call this like a "plugin system", is
+A patch system comprises a collection of patch files (refer to man patch(1) for detailed information) designed to modify an existing Sentry configuration. This allows for targeted adjustments to achieve specific operational goals, optimizing Sentry's functionality within your current environment. This approach provides a flexible alternative to a full, customized re-installation, enabling users to adapt Sentry to their specific needs with greater efficiency.
-a collection of patch files (see [man patch(1)](https://man7.org/linux/man-pages/man1/patch.1.html))
+
-that can be used with to modify the existing configuration to achieve
+We also actively encourage the community to contribute! If you've developed a patch that enhances your self-hosted Sentry experience, consider submitting a pull request. Your contributions can be invaluable to other users facing similar challenges, fostering a collaborative environment where shared solutions benefit everyone.
-the desired goal.
 
 > [!WARNING]
 > Beware that this is very experimental and might not work as expected.
@@ -14,28 +13,38 @@ the desired goal.
 
 ## How to use patches
 
-The patches are designed mostly to help modify the existing
+The patches are designed mostly to help modify the existing configuration files. You will need to run the `install.sh` script afterwards.
-configuration files. You will need to run the `install.sh` script
-afterwards.
 
-They should be run from the root directory. For example, the
+They should be run from the root directory. For example, the `external-kafka` patches should be run as:
-`external-kafka` patches should be run as:
 
 ```bash
-patch < optional-modifications/patches/external-kafka/.env.patch
+patch -p0 < optional-modifications/patches/external-kafka/.env.patch
-patch < optional-modifications/patches/external-kafka/config.example.yml.patch
+patch -p0 < optional-modifications/patches/external-kafka/config.example.yml.patch
-patch < optional-modifications/patches/external-kafka/sentry.conf.example.py.patch
+patch -p0 < optional-modifications/patches/external-kafka/sentry.conf.example.py.patch
-patch < optional-modifications/patches/external-kafka/docker-compose.yml.patch
+patch -p0 < optional-modifications/patches/external-kafka/docker-compose.yml.patch
 ```
 
-Some patches might require additional steps to be taken, like providing
+The `-p0` flag is important to ensure the patch applies to the correct absolute file path.
-credentials or additional TLS certificates.
+
+Some patches might require additional steps to be taken, like providing credentials or additional TLS certificates. Make sure to see your changed files before running the `install.sh` script.
+
+## How to create patches
+
+1. Copy the original file to a temporary file name. For example, if you want to create a `clustered-redis` patch, you might want to copy `docker-compose.yml` to `docker-compose.clustered-redis.yml`.
+2. Make your changes on the `docker-compose.clustered-redis.yml` file.
+3. Run the following command to create the patch:
+    ```bash
+    diff -Naru docker-compose.yml docker-compose.clustered-redis.yml > docker-compose.yml.patch
+    ```
+    Or the template command:
+    ```bash
+    diff -Naru [original file] [patched file] > [destination file].patch
+    ```
+4. Create a new directory in the `optional-modifications/patches` folder with the name of the patch. For example, `optional-modifications/patches/clustered-redis`.
+5. Move the patched files (like `docker-compose.yml.patch` earlier) into the new directory.
 
 ## Official support
 
-Sentry employees are not obliged to provide dedicated support for
+While Sentry employees aren't able to offer dedicated support for these patches, they can provide valuable information to help move things forward. Ultimately, we really encourage the community to take the wheel, maintaining and fostering these patches themselves. If you have questions, Sentry employees will be there to help guide you.
-patches, but they can help by providing information to move us forward.
-We encourage the community to contribute for any bug fixes or
-improvements.
 
 See the [support policy for self-hosted Sentry](https://develop.sentry.dev/self-hosted/support/) for more information.

optional-modifications/_lib.sh

@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-
-set -euo pipefail
-test "${DEBUG:-}" && set -x
-
-function patch_file() {
-  target="$1"
-  content="$2"
-  if [[ -f "$target" ]]; then
-    echo "🙈 Patching $target ..."
-    patch -p1 <"$content"
-  else
-    echo "🙊 Skipping $target ..."
-  fi
-}

optional-modifications/patches/external-kafka/docker-compose.yml.patch

@@ -1,5 +1,5 @@
---- docker-compose.yml	2025-03-17 13:32:15.120328412 +0700
+--- docker-compose.yml	2025-07-08 10:22:36.600616503 +0700
-+++ docker-compose.external-kafka.yml	2025-05-15 08:39:05.509951068 +0700
++++ docker-compose.external-kafka.yml	2025-07-08 10:36:44.069900011 +0700
 @@ -26,8 +26,6 @@
    depends_on:
      redis:
@@ -48,7 +48,7 @@
      REDIS_HOST: redis
      UWSGI_MAX_REQUESTS: "10000"
      UWSGI_DISABLE_LOGGING: "true"
-@@ -140,43 +151,7 @@
+@@ -136,43 +147,7 @@
        POSTGRES_HOST_AUTH_METHOD: "trust"
      volumes:
        - "sentry-postgres:/var/lib/postgresql/data"
@@ -93,7 +93,7 @@
    clickhouse:
      <<: *restart_policy
      image: clickhouse-self-hosted-local
-@@ -475,9 +450,8 @@
+@@ -509,9 +484,8 @@
          read_only: true
          source: ./geoip
          target: /geoip
@@ -104,7 +104,32 @@
        redis:
          <<: *depends_on-healthy
        web:
-@@ -486,15 +460,21 @@
+@@ -520,8 +494,22 @@
+     <<: *restart_policy
+     image: "$TASKBROKER_IMAGE"
+     environment:
+-      TASKBROKER_KAFKA_CLUSTER: "kafka:9092"
+-      TASKBROKER_KAFKA_DEADLETTER_CLUSTER: "kafka:9092"
++      TASKBROKER_KAFKA_CLUSTER: ${KAFKA_BOOTSTRAP_SERVERS:-kafka:9092}
++      TASKBROKER_KAFKA_SECURITY_PROTOCOL: ${KAFKA_SECURITY_PROTOCOL:-PLAINTEXT}
++      TASKBROKER_KAFKA_SSL_CA_LOCATION: ${KAFKA_SSL_CA_LOCATION:-}
++      TASKBROKER_KAFKA_SSL_CERTIFICATE_LOCATION: ${KAFKA_SSL_CERTIFICATE_LOCATION:-}
++      TASKBROKER_KAFKA_SSL_KEY_LOCATION: ${KAFKA_SSL_KEY_LOCATION:-}
++      TASKBROKER_KAFKA_SASL_MECHANISM: ${KAFKA_SASL_MECHANISM:-}
++      TASKBROKER_KAFKA_SASL_USERNAME: ${KAFKA_SASL_USERNAME:-}
++      TASKBROKER_KAFKA_SASL_PASSWORD: ${KAFKA_SASL_PASSWORD:-}
++      TASKBROKER_KAFKA_DEADLETTER_CLUSTER: ${KAFKA_BOOTSTRAP_SERVERS:-kafka:9092}
++      TASKBROKER_KAFKA_DEADLETTER_SECURITY_PROTOCOL: ${KAFKA_SECURITY_PROTOCOL:-PLAINTEXT}
++      TASKBROKER_KAFKA_DEADLETTER_SSL_CA_LOCATION: ${KAFKA_SSL_CA_LOCATION:-}
++      TASKBROKER_KAFKA_DEADLETTER_SSL_CERTIFICATE_LOCATION: ${KAFKA_SSL_CERTIFICATE_LOCATION:-}
++      TASKBROKER_KAFKA_DEADLETTER_SSL_KEY_LOCATION: ${KAFKA_SSL_KEY_LOCATION:-}
++      TASKBROKER_KAFKA_DEADLETTER_SASL_MECHANISM: ${KAFKA_SASL_MECHANISM:-}
++      TASKBROKER_KAFKA_DEADLETTER_SASL_USERNAME: ${KAFKA_SASL_USERNAME:-}
++      TASKBROKER_KAFKA_DEADLETTER_SASL_PASSWORD: ${KAFKA_SASL_PASSWORD:-}
+       TASKBROKER_DB_PATH: "/opt/sqlite/taskbroker-activations.sqlite"
+     volumes:
+       - sentry-taskbroker:/opt/sqlite
+@@ -538,15 +526,21 @@
      <<: *restart_policy
      image: "$VROOM_IMAGE"
      environment:
@@ -131,7 +156,32 @@
      profiles:
        - feature-complete
    vroom-cleanup:
-@@ -523,8 +503,6 @@
+@@ -571,7 +565,14 @@
+     image: "$UPTIME_CHECKER_IMAGE"
+     command: run
+     environment:
+-      UPTIME_CHECKER_RESULTS_KAFKA_CLUSTER: kafka:9092
++      UPTIME_CHECKER_RESULTS_KAFKA_CLUSTER: ${KAFKA_BOOTSTRAP_SERVERS:-kafka:9092}
++      UPTIME_CHECKER_KAFKA_SECURITY_PROTOCOL: ${KAFKA_SECURITY_PROTOCOL:-PLAINTEXT}
++      UPTIME_CHECKER_KAFKA_SSL_CA_LOCATION: ${KAFKA_SSL_CA_LOCATION:-}
++      UPTIME_CHECKER_KAFKA_SSL_CERT_LOCATION: ${KAFKA_SSL_CERTIFICATE_LOCATION:-}
++      UPTIME_CHECKER_KAFKA_SSL_KEY_LOCATION: ${KAFKA_SSL_KEY_LOCATION:-}
++      UPTIME_CHECKER_KAFKA_SASL_MECHANISM: ${KAFKA_SASL_MECHANISM:-}
++      UPTIME_CHECKER_KAFKA_SASL_USERNAME: ${KAFKA_SASL_USERNAME:-}
++      UPTIME_CHECKER_KAFKA_SASL_PASSWORD: ${KAFKA_SASL_PASSWORD:-}
+       UPTIME_CHECKER_REDIS_HOST: redis://redis:6379
+       # Set to `true` will allow uptime checks against private IP addresses
+       UPTIME_CHECKER_ALLOW_INTERNAL_IPS: "false"
+@@ -582,8 +583,6 @@
+       # resolver.
+       #UPTIME_CHECKER_HTTP_CHECKER_DNS_NAMESERVERS: "8.8.8.8,8.8.4.4"
+     depends_on:
+-      kafka:
+-        <<: *depends_on-healthy
+       redis:
+         <<: *depends_on-healthy
+     profiles:
+@@ -597,8 +596,6 @@
      external: true
    sentry-redis:
      external: true