Skip to content

Suggestion: Add "Building from Source" guide to the Wiki #153

@alexwilson1

Description

@alexwilson1

Hi Maintainers,

I've been using DetoxDroid and noticed there isn't a guide for developers who want to fork the repo and create their own builds using the included GitHub Actions workflow. This would be really helpful for contributors and those who want to experiment (but requires this PR for the build to function on a fork).

I've written up a guide and would like to propose adding it as a new page to the wiki, perhaps titled Building from Source.

Here is the full markdown content:


# Building the App from Source

This guide is for developers who want to create their own signed builds of DetoxDroid from a forked repository. The project includes a GitHub Actions workflow that automates the entire process of versioning, building, signing, and releasing the application.

## Prerequisites

- A [GitHub](https://github.com/) account.
- [Docker](https://www.docker.com/products/docker-desktop/) installed on your local machine (for generating the signing key).
- You have forked this repository to your own GitHub account.

## Step-by-Step Guide

### Step 1: Fork the Repository

If you haven't already, click the "Fork" button at the top-right of this repository's page to create your own copy.

### Step 2: Generate an Android App Signing Key

To create a release build of an Android app, you need a cryptographic key to sign it. This key proves that you are the author of the app.

1.  Open a terminal or command prompt in a directory where you want to store your key.
2.  Run the following command. This uses a Docker container with OpenJDK to ensure you don't need to install Java locally.

    ```bash
    docker run --rm -v "$PWD":/work -w /work openjdk:21 \
      keytool -genkey -v \
      -keystore my-release-key.keystore \
      -alias my-key-alias \
      -keyalg RSA -keysize 2048 -validity 10000 \
      -storepass YOUR_PASSWORD -keypass YOUR_PASSWORD \
      -dname "CN=Your Name, OU=Your Org, O=Personal, L=City, S=State, C=US"
    ```

3.  **Important:**
    *   Replace `YOUR_PASSWORD` with a strong, unique password. The build workflow requires the keystore password (`storepass`) and the key password (`keypass`) to be the same.
    *   You can change the `-alias` and the `-dname` fields, but remember the alias for the next steps.
    *   This command will create a file named `my-release-key.keystore` in your current directory. **Treat this file and your password as highly sensitive. Do not commit them to your repository.**

### Step 3: Encode the Keystore File

The GitHub Actions workflow needs the keystore file, but we can't commit it directly. Instead, we'll provide it as a Base64-encoded secret.

*   **On macOS or Linux:**

    ```bash
    base64 -i my-release-key.keystore
    ```

*   **On Windows (in Command Prompt):**

    ```bash
    certutil -encode my-release-key.keystore encoded.txt && type encoded.txt
    ```

Copy the entire block of text that is output by this command. It will be a long string of characters.

### Step 4: Set Up GitHub Secrets

In your forked repository on GitHub, navigate to **Settings > Secrets and variables > Actions**.

Click the **New repository secret** button to add the following secrets. These names must match exactly, as they are used by the build workflow (`.github/workflows/publish.yaml`).

| Secret Name              | Value                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| `SIGNING_KEY`            | Paste the entire Base64-encoded string from the previous step.     |
| `SIGNING_KEY_ALIAS`      | The alias you used in the `keytool` command (e.g., `my-key-alias`).  |
| `KEY_STORE_PASSWORD`     | The password you chose for your keystore (`storepass`).            |
| `KEY_PASSWORD`           | The password for your key (`keypass`). Must be same as above.      |

### Step 5: Trigger the Build

The workflow is set up to run manually.

1.  Go to the **Actions** tab in your forked repository.
2.  In the left sidebar, click on the **Publish Android App** workflow.
3.  You will see a message: "This workflow has a `workflow_dispatch` event trigger." Click the **Run workflow** dropdown on the right.
4.  You can leave the `force-bump` field blank to let the workflow automatically determine the version based on your commit history, or you can specify `patch`, `minor`, or `major` to force a specific version bump.
5.  Click the green **Run workflow** button.

## What Happens Next?

The GitHub Action will now:
1.  Check out your code.
2.  Automatically determine the next version number based on your commits (or your forced input).
3.  Update the `versionCode` and `versionName` in `app/build.gradle.kts`.
4.  Generate a changelog file for the new version.
5.  Decode your `SIGNING_KEY` secret back into a keystore file.
6.  Build and sign the release APK using your secrets.
7.  Commit the version and changelog updates back to your repository.
8.  Create a new Git tag (e.g., `v0.1.4`).
9.  Create a new GitHub Release, attaching the signed APK and the changelog.

Once the action is complete, you can find your signed APK in the **Releases** section of your forked repository.

Thanks for considering it!

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions