SPARC/docs/CONTAINER_REGISTRY.md

# Container Registry and CI/CD Setup

This document explains how to build and push Docker images using Gitea Actions and the Gitea Container Registry.

## Overview

The SPARC project uses Gitea Actions (GitHub Actions-compatible) to automatically build and push Docker images to the Gitea Container Registry whenever code is pushed to the repository.

## Workflow Configuration

The workflow is defined in `.gitea/workflows/build.yaml` and automatically:
- Builds the Docker image from the `Dockerfile`
- Tags the image appropriately based on the git ref (branch/tag)
- Pushes to the Gitea Container Registry at `10.0.1.10`

### Triggers

The workflow runs on:
- **Push to main branch**: Builds and tags with commit SHA + `latest`
- **Push of tags**: Builds and tags with the tag name + `latest`
- **Manual dispatch**: Can be triggered manually from Gitea UI

### Image Naming

Images are pushed to: `10.0.1.10/0xwheatyz/sparc:<tag>`

- Main branch commits: `10.0.1.10/0xwheatyz/sparc:<sha>` and `10.0.1.10/0xwheatyz/sparc:latest`
- Tags: `10.0.1.10/0xwheatyz/sparc:<tag-name>` and `10.0.1.10/0xwheatyz/sparc:latest`
- Other branches: `10.0.1.10/0xwheatyz/sparc:<branch-name>`

## Prerequisites

### 1. Enable Container Registry in Gitea

The Gitea instance must have the Container Registry (Packages) feature enabled:

1. Access Gitea as administrator
2. Go to Site Administration > Configuration
3. Find "Packages" section
4. Ensure packages/container registry is enabled

### 2. Create Personal Access Token

The workflow needs a personal access token with package write permissions:

1. In Gitea UI, click your profile → Settings
2. Go to Applications → Manage Access Tokens
3. Click "Generate New Token"
4. Give it a descriptive name (e.g., "Actions Container Registry")
5. Select scopes:
   - `write:package` (required)
   - `read:package` (required)
6. Click "Generate Token"
7. **Copy the token immediately** (you won't see it again)

### 3. Add Token as Repository Secret

1. Go to your repository in Gitea
2. Click Settings → Secrets
3. Click "Add Secret"
4. Name: `GITEA_TOKEN`
5. Value: Paste the personal access token
6. Click "Add Secret"

## Usage

### Automatic Builds

Once configured, the workflow runs automatically:

```bash
# Push to main branch - triggers build
git add .
git commit -m "feat: add new feature"
git push origin main

# Create and push a tag - triggers build with tag
git tag v1.0.0
git push origin v1.0.0
```

### Manual Builds

You can also trigger builds manually:

1. Go to repository → Actions
2. Click on "Build and Push Docker Image" workflow
3. Click "Run workflow"
4. Select the branch
5. Click "Run workflow"

### Monitor Build Progress

1. Go to repository → Actions
2. Click on the running workflow
3. View logs for each step

## Pulling Images

Once built, images can be pulled from the registry:

```bash
# Log in to registry
docker login 10.0.1.10 -u your-username

# Pull the latest image
docker pull 10.0.1.10/0xwheatyz/sparc:latest

# Pull a specific tag
docker pull 10.0.1.10/0xwheatyz/sparc:v1.0.0

# Pull a specific commit
docker pull 10.0.1.10/0xwheatyz/sparc:abc1234
```

## Troubleshooting

### Workflow Fails at Login Step

**Error**: `Error response from daemon: login attempt to http://10.0.1.10/v2/ failed with status: 404 Not Found`

**Solution**: Container registry is not enabled in Gitea. Contact administrator to enable packages feature.

### Workflow Fails with 401 Unauthorized

**Error**: `unauthorized: authentication required`

**Solutions**:
1. Verify `GITEA_TOKEN` secret exists and is correct
2. Verify token has `write:package` and `read:package` scopes
3. Regenerate token if it has expired

### Workflow Fails at Push Step

**Error**: `denied: permission denied`

**Solutions**:
1. Ensure your user account has write access to the repository
2. Verify the token has the correct permissions
3. Check if the repository owner matches the registry path

### Image Not Appearing in Packages

**Check**:
1. Go to repository → Packages tab
2. If no packages appear, check workflow logs for errors
3. Verify the image was successfully pushed (check workflow output)

## Advanced Configuration

### Using a Different Registry

To push to a different container registry (e.g., Docker Hub, GHCR):

1. Update the `REGISTRY` variable in `.gitea/workflows/build.yaml`
2. Update the login step with appropriate credentials
3. Add registry credentials as secrets

### Building Multi-platform Images

To build for multiple architectures:

```yaml
- name: Build Docker image
  run: |
    docker buildx build \
      --platform linux/amd64,linux/arm64 \
      -t ${{ steps.tags.outputs.IMAGE_TAG }} \
      --push .
```

### Adding Build Arguments

To pass build arguments:

```yaml
- name: Build Docker image
  run: |
    docker build \
      --build-arg VERSION=${{ gitea.sha_short }} \
      -t ${{ steps.tags.outputs.IMAGE_TAG }} .
```

## References

- [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/overview)
- [Gitea Packages Documentation](https://docs.gitea.com/usage/packages/overview)
- [GitHub Actions Syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) (Gitea Actions compatible)