# Docker & CI/CD Setup for JellyTau

This document explains how to use the Docker configuration and Gitea Act CI/CD pipeline for building and testing JellyTau.

## Overview

The setup includes:

- Dockerfile.builder: Pre-built image with all dependencies (push to your registry)
- Dockerfile: Multi-stage build for local testing and building
- docker-compose.yml: Orchestration for local development and testing
- .gitea/workflows/build-and-test.yml: Automated CI/CD pipeline using pre-built builder image

### Quick Start

For CI/CD (Gitea Actions):

1. Build and push builder image (see build-builder-image.md)
2. Push to master branch - workflow runs automatically
3. Check Actions tab for results and APK artifacts

For Local Testing:

    docker-compose run test       # Run tests
    docker-compose run android-build  # Build APK
    docker-compose run dev        # Interactive shell

## Docker Usage

### Prerequisites

- Docker Engine 20.10+
- Docker Compose 2.0+ (if using docker-compose)
- At least 10GB free disk space (for Android SDK and build artifacts)

### Building the Docker Image

    # Build the complete image
    docker build -t jellytau:latest .

    # Build specific target
    docker build -t jellytau:test --target test .
    docker build -t jellytau:android --target android-build .

### Using Docker Compose

#### Run Tests Only

    docker-compose run test

This will:

1. Install all dependencies
2. Run frontend tests (Vitest)
3. Run Rust backend tests
4. Report results

#### Build Android APK

    docker-compose run android-build

This will:

1. Run tests first (depends on test service)
2. If tests pass, build the Android APK
3. Output APK files to `src-tauri/gen/android/app/build/outputs/apk/`

#### Interactive Development

    docker-compose run dev

This starts an interactive shell with all development tools available. From here you can:

    bun install
    bun run build
    bun test
    bun run tauri android build --apk true

#### Run All Services in Sequence

    docker-compose up --abort-on-container-exit

### Extracting Build Artifacts

After a successful build, APK files are located in:

    src-tauri/gen/android/app/build/outputs/apk/

Copy to your host machine:

    docker cp jellytau-android-build:/app/src-tauri/gen/android/app/build/outputs/apk ./apk-output

## Gitea Act CI/CD Pipeline

The `.gitea/workflows/build-and-test.yml` workflow automates:

Single Job: Runs on every push to `master` and PRs

- Uses pre-built builder image (no setup time)
- Installs project dependencies
- Runs frontend tests (Vitest)
- Runs Rust backend tests
- Builds the frontend
- Builds the Android APK
- Uploads APK as artifact (30-day retention)

The workflow skips markdown files to avoid unnecessary builds.

### Workflow Triggers

The workflow runs on:

- Push to `master` or `main` branches
- Pull requests to `master` or `main` branches
- Can be extended with: `workflow_dispatch` for manual triggers

### Setting Up the Builder Image

Before using the CI/CD pipeline, you must build and push the builder image:

    # Build the image
    docker build -f Dockerfile.builder -t jellytau-builder:latest .

    # Tag for your registry
    docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest

    # Push to registry
    docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest

See build-builder-image.md for detailed instructions.

### Setting Up Gitea Act

1. Ensure builder image is pushed (see above)

2. Push to Gitea repository: The workflow will automatically trigger on push to `master` or pull requests

3. View workflow runs in Gitea UI:

   - Navigate to your repository
   - Go to Actions tab
   - Click on workflow runs to see logs

4. Test locally (optional):

       # Install act if needed
       curl https://gitea.com/actions/setup-act/releases/download/v0.25.0/act-0.25.0-linux-x86_64.tar.gz | tar xz

       # Run locally (requires builder image to be available)
       ./act push --file .gitea/workflows/build-and-test.yml

### Customizing the Workflow

#### Modify Build Triggers

Edit `.gitea/workflows/build-and-test.yml` to change when builds run:

    on:
      push:
        branches:
          - master
          - develop  # Add more branches
        paths:
          - 'src/**'  # Only run if src/ changes
          - 'src-tauri/**'  # Only run if Rust code changes

#### Add Notifications

Add Slack, Discord, or email notifications on build completion:

    - name: Notify on success
      if: success()
      run: |
        curl -X POST https://slack-webhook-url...

#### Customize APK Upload

Modify artifact retention or add to cloud storage:

    - name: Upload APK to S3
      uses: actions/s3-sync@v1
      with:
        aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY }}
        aws_secret_access_key: ${{ secrets.AWS_SECRET_KEY }}
        aws_bucket: my-apk-bucket
        source_dir: src-tauri/gen/android/app/build/outputs/apk/

## Environment Setup in CI

### Secret Variables

To use secrets in the workflow, set them in Gitea:

1. Go to Repository Settings → Secrets
2. Add secrets like:
   - `AWS_ACCESS_KEY` for S3 uploads
   - `SLACK_WEBHOOK_URL` for notifications
   - `GITHUB_TOKEN` for releases (pre-configured)

## Troubleshooting

### Out of Memory During Build

Android builds are memory-intensive. If you get OOM errors:

    # Limit memory in docker-compose
    services:
      android-build:
        deploy:
          resources:
            limits:
              memory: 6G

Or increase Docker's memory allocation in Docker Desktop settings.

### Android SDK Download Timeout

If downloads timeout, increase timeout or download manually:

    # In container, with longer timeout
    timeout 600 sdkmanager --sdk_root=$ANDROID_HOME ...

### Rust Compilation Errors

Make sure Rust is updated:

    rustup update
    rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android

### Cache Issues

Clear Docker cache and rebuild:

    docker-compose down -v  # Remove volumes
    docker system prune      # Clean up dangling images
    docker-compose up --build

## Performance Tips

1. Cache Reuse: Both Docker and Gitea Act cache dependencies across runs
2. Parallel Steps: The workflow runs frontend and Rust tests in series; consider parallelizing for faster CI
3. Incremental Builds: Rust and Node caches persist between runs
4. Docker Buildkit: Enable for faster builds:

       DOCKER_BUILDKIT=1 docker build .

## Security Considerations

- Dockerfile uses `ubuntu:24.04` base image from official Docker Hub
- NDK is downloaded from official Google servers (verified via HTTPS)
- No credentials are stored in the Dockerfile
- Use Gitea Secrets for sensitive values (API keys, tokens, etc.)
- Lock dependency versions in `Cargo.toml` and `package.json`

## Next Steps

1. Test locally with `docker-compose up`
2. Push to your Gitea repository
3. Monitor workflow runs in the Actions tab
4. Configure secrets in repository settings for production builds
5. Set up artifact retention policies (currently 30 days)

## References

- Gitea Actions Documentation
- Docker Multi-stage Builds
- Android Build Tools
- Tauri Android Guide