Initial commit

docs/GITEA_REGISTRY_FIX.md

@@ -0,0 +1,194 @@
+# Gitea Container Registry - Image Naming Fix
+
+## Issue
+
+The initial build script was using incorrect image naming convention for Gitea's container registry.
+
+### Incorrect Format
+
+```
+gitea.harkon.co.uk/ai-tax-agent/svc-ingestion:v1.0.0
+```
+
+### Correct Format (Per Gitea Documentation)
+
+```
+gitea.harkon.co.uk/{owner}/{image}:{tag}
+```
+
+Where `{owner}` must be your **Gitea username** or **organization name**.
+
+**Using organization:** `harkon` (Gitea team/organization)
+
+## Solution
+
+Updated the build script and production compose files to use the correct naming convention.
+
+### Changes Made
+
+#### 1. Build Script (`scripts/build-and-push-images.sh`)
+
+**Before:**
+
+```bash
+REGISTRY="${1:-gitea.harkon.co.uk}"
+VERSION="${2:-latest}"
+PROJECT="ai-tax-agent"
+
+IMAGE_NAME="$REGISTRY/$PROJECT/$service:$VERSION"
+```
+
+**After:**
+
+```bash
+REGISTRY="${1:-gitea.harkon.co.uk}"
+VERSION="${2:-latest}"
+OWNER="${3:-harkon}"  # Gitea organization/team name
+
+IMAGE_NAME="$REGISTRY/$OWNER/$service:$VERSION"
+```
+
+#### 2. Production Services (`infra/compose/production/services.yaml`)
+
+**Before:**
+
+```yaml
+svc-ingestion:
+  image: gitea.harkon.co.uk/ai-tax-agent/svc-ingestion:latest
+```
+
+**After:**
+
+```yaml
+svc-ingestion:
+  image: gitea.harkon.co.uk/harkon/svc-ingestion:latest
+```
+
+All 14 services updated:
+
+- svc-ingestion
+- svc-extract
+- svc-kg
+- svc-rag-retriever
+- svc-rag-indexer
+- svc-forms
+- svc-hmrc
+- svc-ocr
+- svc-rpa
+- svc-normalize-map
+- svc-reason
+- svc-firm-connectors
+- svc-coverage
+- ui-review
+
+## Usage
+
+### Build and Push Images
+
+```bash
+# With default owner (harkon organization)
+./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1
+
+# With custom owner
+./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1 <your-gitea-org>
+```
+
+### Pull Images
+
+```bash
+docker pull gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
+```
+
+### Push Images Manually
+
+```bash
+# Tag image
+docker tag my-image:latest gitea.harkon.co.uk/harkon/my-image:v1.0.1
+
+# Push image
+docker push gitea.harkon.co.uk/harkon/my-image:v1.0.1
+```
+
+## Gitea Registry Documentation Reference
+
+From Gitea's official documentation:
+
+### Image Naming Convention
+
+Images must follow this naming convention:
+
+```
+{registry}/{owner}/{image}
+```
+
+When building your docker image, using the naming convention above, this looks like:
+
+```bash
+# build an image with tag
+docker build -t {registry}/{owner}/{image}:{tag} .
+
+# name an existing image with tag
+docker tag {some-existing-image}:{tag} {registry}/{owner}/{image}:{tag}
+```
+
+### Valid Examples
+
+For owner `testuser` on `gitea.example.com`:
+
+- ✅ `gitea.example.com/testuser/myimage`
+- ✅ `gitea.example.com/testuser/my-image`
+- ✅ `gitea.example.com/testuser/my/image`
+
+### Important Notes
+
+1. **Owner must exist**: The owner (username or organization) must exist in Gitea
+2. **Case-insensitive tags**: `image:tag` and `image:Tag` are treated as the same
+3. **Authentication required**: Use personal access token with `write:package` scope
+4. **Registry URL**: Use the main Gitea domain, not a separate registry subdomain
+
+## Verification
+
+After the fix, verify images are pushed correctly:
+
+```bash
+# Login to Gitea
+docker login gitea.harkon.co.uk
+
+# Check pushed images in Gitea UI
+# Navigate to: https://gitea.harkon.co.uk/blue/-/packages
+```
+
+## Current Build Status
+
+✅ **Fixed and working!**
+
+Build command:
+
+```bash
+./scripts/build-and-push-images.sh gitea.harkon.co.uk v1.0.1 harkon
+```
+
+Expected output:
+
+```
+ℹ️  Logging in to registry: gitea.harkon.co.uk
+Login Succeeded
+ℹ️  Building svc-ingestion...
+ℹ️  Building: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
+✅ Built: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
+ℹ️  Pushing: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
+✅ Pushed: gitea.harkon.co.uk/harkon/svc-ingestion:v1.0.1
+```
+
+## Next Steps
+
+1. ✅ Build script fixed
+2. ✅ Production compose files updated
+3. 🟡 Build in progress (14 services)
+4. ⏳ Deploy to production (after build completes)
+
+## References
+
+- [Gitea Container Registry Documentation](https://docs.gitea.com/usage/packages/container)
+- Build script: `scripts/build-and-push-images.sh`
+- Production services: `infra/compose/production/services.yaml`