From 276fdccf3632d994328f8f371e98f66e4f590a74 Mon Sep 17 00:00:00 2001
From: irl <iain@learmonth.me>
Date: Mon, 28 Apr 2025 15:13:15 +0100
Subject: [PATCH] build: remove requirement to edit docker-compose.yml
 per-stage

---
 README.md                   | 57 +++++++++++++++++++++++++++++++++----
 docker-compose.override.yml |  4 +++
 docker-compose.yml          | 18 ++++++------
 legacy/README.md            |  8 ++----
 4 files changed, 67 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index d51577b..6e292e1 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,58 @@
-ilo sitelen tu
-==============
+# ✍️ ilo sitelen tu
 
 A rewriting proxy service for use as the backend of a live web mirroring service for resilient and robust access to your website.
 
 ---
 
-Origin Configuration
---------------------  
+## 🏃 Running with Docker Compose
+
+You can run the application using Docker Compose in different environments using the appropriate Compose files and
+profiles.
+
+### 🔧 Production
+
+To run in **production**, use only the base `docker-compose.yml` file:
+
+```bash
+docker-compose -f docker-compose.yml up
+```
+
+This will start the core services (rewriting proxy and redis backend) without exposing any development-specific
+configurations or ports.
+
+### 🧪 Staging
+
+To run in **staging**, include the `override` file which may expose additional ports or settings:
+
+```bash
+docker-compose -f docker-compose.yml -f docker-compose.override.yml up
+```
+
+This setup is useful for testing in an environment that closely mirrors production but includes conveniences like
+exposing the Redis port on localhost.
+
+### 💻 Local Development
+
+For **local development**, use the same staging command:
+
+```bash
+docker-compose -f docker-compose.yml -f docker-compose.override.yml up
+```
+
+### 🛠 Enabling the Legacy Updater Tool (Optional)
+
+The Legacy Updater Tool is an optional service that can be enabled using the `legacy` profile.
+The tool requires [additional configuration](./legacy/README.md).
+
+To include it, use the `--profile` argument to `docker compose`:
+
+```bash
+docker-compose --profile legacy up
+```
+
+Without the `--profile legacy` flag, the updater tool is disabled by default.
+
+## ⚙️ Origin Configuration
 
 Each origin is required to have a JSON configuration object available in the Redis backend under the key  
 `jasima:config:<canonical host>`.  
@@ -25,8 +71,7 @@ The following keys are meaningful in this object:
 
 Note: the default case applies when the key is omitted.
 
-Copyright
----------
+## 🖋️ Copyright
 
 Copyright © 2025 SR2 Communications Limited.
 
diff --git a/docker-compose.override.yml b/docker-compose.override.yml
index e69de29..7eebc99 100644
--- a/docker-compose.override.yml
+++ b/docker-compose.override.yml
@@ -0,0 +1,4 @@
+services:
+  redis:
+    ports:
+      - "127.0.0.1:6379:6379"
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
index 3afc8a8..810a17a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -7,14 +7,14 @@ services:
     ports:
       - "80:80"
       - "443:443"
-#  updater:
-#    build:
-#      context: legacy
-#      dockerfile: Dockerfile
-#    env_file: "updater.env"
-#    volumes:
-#      - ./legacy/configs:/configs
   redis:
     image: redis:latest
-#    ports:
-#      - "127.0.0.1:6379:6379"
+  updater:
+    build:
+      context: legacy
+      dockerfile: Dockerfile
+    env_file: "updater.env"
+    volumes:
+      - ./legacy/configs:/configs
+    profiles:
+      - legacy
diff --git a/legacy/README.md b/legacy/README.md
index aba6763..4097920 100644
--- a/legacy/README.md
+++ b/legacy/README.md
@@ -1,12 +1,10 @@
-Legacy Updater Tool
-===================
+# 🔄 Legacy Updater Tool
 
 This updater exists to facilitate a transition from the legacy mirrors orchestration to its replacement.
 As far as I know, no one else has ever deployed the original orchestrator so this will almost certainly not be useful
 to you.
 
-Configuration
--------------
+## ⚙️ Configuration
 
 When working with the Docker Compose file, configure the sources via the environment file: `updater.env`.
 One environment variable per configured pool with an HTTP URL to the Bypass Censorship Mirrors JSON file for each pool.
@@ -17,7 +15,7 @@ For example:
 JASIMA_MIRRORS_POOL_example=https://www.example.com/mirrors.json
 ```
 
-### Per-site Configurations
+### 🌐 Per-site Configurations
 
 In the configs directory, create a file named `default.json` to provide the default site configuration.
 Create files named `<host>.json` to override the default.