jellytau/docs/build/docker.md

# 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](build-builder-image.md))
2. Push to master branch - workflow runs automatically
3. Check Actions tab for results and APK artifacts

**For Local Testing**:
```bash
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

```bash
# 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
```bash
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
```bash
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
```bash
docker-compose run dev
```

This starts an interactive shell with all development tools available. From here you can:
```bash
bun install
bun run build
bun test
bun run tauri android build --apk true
```

#### Run All Services in Sequence
```bash
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:
```bash
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:

```bash
# 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](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):
   ```bash
   # 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:

```yaml
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:

```yaml
- 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:

```yaml
- 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:

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

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

### Rust Compilation Errors
Make sure Rust is updated:

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

### Cache Issues
Clear Docker cache and rebuild:

```bash
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:
   ```bash
   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](https://docs.gitea.io/en-us/actions/)
- [Docker Multi-stage Builds](https://docs.docker.com/build/building/multi-stage/)
- [Android Build Tools](https://developer.android.com/studio/command-line)
- [Tauri Android Guide](https://tauri.app/v1/guides/building/android)