chore: clean up repo organization

- Standardize on bun: remove package-lock.json, add packageManager field, gitignore non-bun lockfiles, fix stray npm install in android:build:clean - Remove stale build logs and empty dirs (src-tauri/plugins, docs/tickets) - Move android-dev.sh into scripts/ - Consolidate root docs into docs/ (docker/builder under docs/build/); move the architecture overview to docs/architecture/README.md - Extract Requirements Specification from README into docs/requirements.md and slim README down to a project intro + docs index - Fix internal references to the moved files
2026-06-21 09:52:09 +02:00
parent ccc9dca924
commit 5ba9e0e958
14 changed files with 500 additions and 10717 deletions
@@ -0,0 +1,156 @@
+# 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/)
@@ -0,0 +1,282 @@
+# 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)