jellytau/BUILD-BUILDER-IMAGE.md

# Building and Pushing the JellyTau Builder Image

This document explains how to create and push the pre-built builder Docker image to your registry for use in Gitea Act CI/CD.

## Prerequisites

- Docker installed and running
- Access to your Docker registry (e.g., `gitea.tourolle.paris`)
- Docker registry credentials configured (`docker login`)

## Building the Builder Image

### Step 1: Build the Image Locally

```bash
# From the project root
docker build -f Dockerfile.builder -t jellytau-builder:latest .
```

This creates a local image with:
- All system dependencies
- Rust with Android targets
- Android SDK and NDK
- Node.js and Bun
- All build tools pre-installed

### Step 2: Tag for Your Registry

Replace `gitea.tourolle.paris/dtourolle` with your actual registry path:

```bash
docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest
```

### Step 3: Login to Your Registry

If not already logged in:

```bash
docker login gitea.tourolle.paris
```

### Step 4: Push to Registry

```bash
docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
```

## Complete One-Liner

```bash
docker build -f Dockerfile.builder -t jellytau-builder:latest . && \
docker tag jellytau-builder:latest gitea.tourolle.paris/dtourolle/jellytau-builder:latest && \
docker push gitea.tourolle.paris/dtourolle/jellytau-builder:latest
```

## Verifying the Build

Check that the image was pushed successfully:

```bash
# List images in your registry (depends on registry API support)
docker search gitea.tourolle.paris/dtourolle/jellytau-builder

# Or pull and test locally
docker pull gitea.tourolle.paris/dtourolle/jellytau-builder:latest
docker run -it gitea.tourolle.paris/dtourolle/jellytau-builder:latest bun --version
```

## Using in CI/CD

The workflow at `.gitea/workflows/build-and-test.yml` automatically uses:
```yaml
container:
  image: gitea.tourolle.paris/dtourolle/jellytau-builder:latest
```

Once pushed, your CI/CD pipeline will use this pre-built image instead of installing everything during the build, saving significant time.

## Updating the Builder Image

When dependencies change (new Rust version, Android SDK update, etc.):

1. Update `Dockerfile.builder` with the new configuration
2. Rebuild and push with a new tag:

```bash
docker build -f Dockerfile.builder -t jellytau-builder:v1.2.0 .
docker tag jellytau-builder:v1.2.0 gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
docker push gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
```

3. Update the workflow to use the new tag:

```yaml
container:
  image: gitea.tourolle.paris/dtourolle/jellytau-builder:v1.2.0
```

## Image Contents

The builder image includes:

- **Base OS**: Ubuntu 24.04
- **Languages**:
  - Rust (stable) with targets: aarch64-linux-android, armv7-linux-androideabi, x86_64-linux-android
  - Node.js 20.x
  - OpenJDK 17 (for Android)
- **Tools**:
  - Bun package manager
  - Android SDK 34
  - Android NDK 27.0.11902837
  - Build essentials (gcc, make, etc.)
  - Git, curl, wget
  - libssl, libclang development libraries
- **Pre-configured**:
  - Rust toolchain components (rustfmt, clippy)
  - Android SDK/NDK environment variables
  - All paths optimized for building

## Build Time

First build takes ~15-20 minutes depending on internet speed (downloads Android SDK/NDK).
Subsequent builds are cached and take seconds.

## Storage

The built image is approximately **4-5 GB**. Ensure your registry has sufficient storage.

## Troubleshooting

### "Image not found" in CI
- Verify the image name matches exactly in the workflow
- Check that the image was successfully pushed: `docker push` output should show successful layers
- Ensure Gitea has access to your registry (check network/firewall)

### Build fails with "command not found"
- The image may not have finished pushing. Wait a few moments and retry the CI job.
- Check that all layers were pushed successfully in the push output.

### Registry authentication in CI
If your registry requires credentials in CI:
1. Create a deploy token in your registry
2. Add to Gitea secrets as `REGISTRY_USERNAME` and `REGISTRY_TOKEN`
3. Use in workflow:
```yaml
- name: Login to Registry
  run: |
    docker login gitea.tourolle.paris -u ${{ secrets.REGISTRY_USERNAME }} -p ${{ secrets.REGISTRY_TOKEN }}
```

## References

- [Docker Build Documentation](https://docs.docker.com/build/)
- [Docker Push Documentation](https://docs.docker.com/engine/reference/commandline/push/)
- [Dockerfile Reference](https://docs.docker.com/engine/reference/builder/)