jellytau/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)
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