From 8ed8fbe061532d75a4aeaecf2cdeb53002fdb526 Mon Sep 17 00:00:00 2001
From: Shihaam Abdul Rahman <shihaam@shihaam.me>
Date: Fri, 11 Jul 2025 18:51:25 +0500
Subject: [PATCH] docs

---
 README.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 164 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..47e1a38
--- /dev/null
+++ b/README.md
@@ -0,0 +1,164 @@
+# Android Builder
+
+A Docker image for building Android applications with Kotlin support. Includes Android SDK, build tools, and Java 17.
+
+## Features
+
+- **Debian Stable** base image
+- **Java 17** (OpenJDK)
+- **Android SDK** with latest command line tools
+- **Android API 35** and Build Tools 35.0.0
+- **NDK** support
+- Network access for dependency downloads
+- Ready for CI/CD pipelines
+
+## Quick Start
+
+### Using with Docker Compose
+
+Create a `compose.yml` in your Android project:
+
+```yaml
+services:
+  release:
+    image: android-builder:latest
+    network_mode: host
+    volumes:
+      - ./release:/release
+      - .:/source
+      - ./path/to/your/keystore.jks:/tmp/key.jks:ro
+    environment:
+      - KEYSTORE_PASSWORD=your_keystore_password
+      - KEY_ALIAS=your_key_alias
+      - KEY_PASSWORD=your_key_password
+```
+
+Run the build:
+```bash
+docker compose run --rm release
+```
+
+### Using with Docker Run
+
+```bash
+docker run --rm \
+  --network host \
+  -v $(pwd):/source \
+  -v $(pwd)/release:/release \
+  -v $(pwd)/keystore.jks:/tmp/key.jks:ro \
+  -e KEYSTORE_PASSWORD=your_password \
+  -e KEY_ALIAS=your_alias \
+  -e KEY_PASSWORD=your_key_password \
+  android-builder:latest
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `KEYSTORE_PASSWORD` | Password for your Android keystore | Yes (for signed builds) |
+| `KEY_ALIAS` | Alias of the key in your keystore | Yes (for signed builds) |
+| `KEY_PASSWORD` | Password for the specific key | Yes (for signed builds) |
+
+## Volume Mounts
+
+| Host Path | Container Path | Description |
+|-----------|----------------|-------------|
+| Your project root | `/source` | Android project source code |
+| Output directory | `/release` | Where built APKs will be placed |
+| Your keystore file | `/tmp/key.jks` | Android signing keystore (read-only) |
+
+## Gradle Configuration
+
+For signed builds, configure your `app/build.gradle.kts`:
+
+```kotlin
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file("/tmp/key.jks")
+            storePassword = System.getenv("KEYSTORE_PASSWORD")
+            keyAlias = System.getenv("KEY_ALIAS")
+            keyPassword = System.getenv("KEY_PASSWORD")
+        }
+    }
+    
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+            // ... other release config
+        }
+    }
+}
+```
+
+## Build Process
+
+The container will:
+1. Make `gradlew` executable
+2. Run `./gradlew assembleRelease`
+3. Copy built APKs to `/release` directory
+
+## Output
+
+After building, you'll find your APKs in the mounted release directory:
+- `app-release.apk` - Signed release APK (if keystore provided)
+- Debug APKs (if building debug variants)
+
+## Creating a Keystore
+
+If you don't have a keystore yet:
+
+```bash
+keytool -genkey -v -keystore keystore.jks \
+  -alias your_alias \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 10000
+```
+
+## Supported Android Versions
+
+- **Target SDK**: 35
+- **Min SDK**: Depends on your project
+- **Build Tools**: 35.0.0
+- **NDK**: 26.1.10909125
+
+## Building the Image
+
+```bash
+docker build -t android-builder:latest .
+```
+
+## CI/CD Usage
+
+This image is perfect for CI/CD pipelines. Example for Gitea Actions:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: android-builder:latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build APK
+        run: |
+          chmod +x ./gradlew
+          ./gradlew assembleRelease
+        env:
+          KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}
+          KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
+          KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
+```
+
+## Troubleshooting
+
+### Network Issues
+If you get `UnknownHostException`, ensure you're using `network_mode: host` in Docker Compose or `--network host` with Docker run.
+
+### Permission Issues
+The container runs as root. If you have permission issues with output files, you may need to adjust file ownership after build.
+
+### Keystore Not Found
+Ensure your keystore path is correct and the file exists on the host system before mounting.