Getting Started

Getting Started

How to get the repo, install the toolchain, pull secrets from Bitwarden, and run a debug build. Works on both Windows (with WSL or git-bash) and headless Ubuntu, which is the canonical build environment per CLI_RELEASE_GUIDE.md.

---

1. Prerequisites

Tool	Version	Notes
JDK	17	AGP 9.0.x requires JDK 17+. Microsoft OpenJDK 17 works fine on Windows (winget install Microsoft.OpenJDK.17).
Android SDK	Platform 36, Build-Tools 36.0.0	Installed via Android Studio's SDK Manager, or via cmdline-tools;latest for headless setups. ANDROID_HOME must point to the SDK root.
Gradle	8.13 (pinned by wrapper)	Don't install system Gradle — just use ./gradlew / gradlew.bat.
Bitwarden CLI (bw)	any current version	Pulls keystore, Firebase config, Play service-account key, etc.
jq	1.6+	Used by retrieve_secrets.sh. On Windows install via winget: winget install jqlang.jq. Avoid the npm jq package — it's broken.
Firebase CLI (firebase)	15+	Only needed if you deploy Firestore rules. npm install -g firebase-tools.
gh CLI	2.x	For tag/release/PR work.

The repo can also be opened in Android Studio Ladybug (2024.2.1) or newer — Studio handles the SDK and JDK for you. The CLI flow exists so the canonical build is reproducible on a headless Linux box.

---

2. Clone

git clone https://github.com/aarshps/varisankya-android.git
cd varisankya-android
git switch main      # only active branch

The default branch is main. The legacy master branch has been removed.

---

3. Pull secrets from Bitwarden

Secrets that are not committed but required to build & sign:

• app/google-services.json — Firebase config (Auth, Firestore, Analytics)
• varisankya-upload-key — Play upload keystore (binary)
• local.properties — release keystore credentials
• app/play_console_key.json — service account for :app:publishBundle

All four are stored as base64-split fields in a Bitwarden secure note called Varisankya. To unpack them locally:

1. Make sure bw is logged in: bw login (one-time). Confirm: bw status should show userEmail set.

2. Drop a .env.local (gitignored) at the repo root with:

   BW_PASSWORD='<your bitwarden master password>'
   

   This lets retrieve_secrets.sh unlock the vault non-interactively. Skip this if you'd rather be prompted each time.

3. Run:

   ./retrieve_secrets.sh

   It will unlock, sync, and write all four files into the working tree.

⚠ Storing a master password in .env.local exposes the vault to anyone who has disk access to the repo. Use only on encrypted disks. Easy alternative: delete .env.local and let the script prompt you each time.

---

4. Configure SDK path

If you haven't already, add this line to local.properties (file is gitignored):

sdk.dir=/absolute/path/to/Android/Sdk

On Windows, escape colons & backslashes: sdk.dir=C\:\\Users\\<you>\\AppData\\Local\\Android\\Sdk. On Linux: sdk.dir=/home/<you>/Android/Sdk.

retrieve_secrets.sh appends the release-keystore fields after this line.

---

5. First build

./gradlew :app:assembleDebug

Artifact at app/build/outputs/apk/debug/app-debug.apk. Install with:

./gradlew :app:installDebug

If you see JAVA_HOME is set to an invalid directory — your JAVA_HOME is pointing at an Android Studio JBR install that doesn't exist. Either install a real JDK 17 and point JAVA_HOME at it, or set it inline:

# PowerShell
$env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-17.0.19.10-hotspot"
.\gradlew.bat :app:assembleDebug

---

6. Sign in test

1. Open the app on a real device or an emulator that has Google Play Services (the standard emulator image works).
2. Tap Sign in with Google, pick a Google account. The Credential Manager flow handles the rest.
3. If you get NoCredentialException or DEVELOPER_ERROR, your debug keystore's SHA-1 isn't registered in Firebase for this app — see Firebase Setup for how to add it.

---

7. Next steps

• Cut a beta / production release → Build & Release
• Read what each file in the codebase does → Architecture
• Add a new screen → keep design tokens consistent per Design System
• Open a PR → Contributing