ai-tax-agent/docs/GITEA_REGISTRY_FIX.md

# 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`