Skip to content

QUICK_REFERENCE.md

Latest commit

 

History

History
367 lines (280 loc) · 7.93 KB

QUICK_REFERENCE.md

File metadata and controls

367 lines (280 loc) · 7.93 KB

Gozar VPN - APK Build & Release Quick Reference Guide

Table of Contents

  1. Environment Setup
  2. Build Commands
  3. Release Commands
  4. Testing & Validation
  5. Troubleshooting
  6. Version Management
  7. Security & Signing

Environment Setup

Prerequisites

# Verify Java installation
java -version

# Verify Android SDK
$ANDROID_HOME/tools/bin/sdkmanager --list

# Verify Gradle
gradle -v

Environment Variables

# Set Android Home
export ANDROID_HOME=~/Android/Sdk
export PATH=$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$PATH

# Verify setup
echo $ANDROID_HOME

Build Commands

Debug Build

# Build debug APK
./gradlew assembleDebug

# Output location: app/build/outputs/apk/debug/

Release Build (Unsigned)

# Build unsigned release APK
./gradlew assembleRelease

# Output location: app/build/outputs/apk/release/

Signed Release Build

# Build signed release APK
./gradlew assembleRelease --build-cache

# Sign with keystore (manual)
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
  -keystore keystore_name.jks \
  app/build/outputs/apk/release/app-release-unsigned.apk \
  key_alias

Build Bundle (AAB)

# Create Android App Bundle for Google Play
./gradlew bundleRelease

# Output location: app/build/outputs/bundle/release/

Build with Specific Build Type

# Build specific variant
./gradlew assemble[BuildType]
# Example: ./gradlew assembleStaging

# Build all variants
./gradlew assemble

Release Commands

Complete Release Workflow

# 1. Clean previous builds
./gradlew clean

# 2. Build release APK
./gradlew assembleRelease

# 3. Sign release APK
jarsigner -verbose -sigalg SHA256withRSA -digestalg SHA-256 \
  -keystore release.jks \
  app/build/outputs/apk/release/app-release-unsigned.apk \
  gozar_vpn_key

# 4. Verify signature
jarsigner -verify -verbose -certs \
  app/build/outputs/apk/release/app-release-unsigned.apk

Google Play Deployment

# Upload to Google Play Console (requires bundlerelease or AAB)
./gradlew bundleRelease

# Manual upload through Google Play Console web interface
# Files: app/build/outputs/bundle/release/app-release.aab

# Or use bundletool for testing before upload:
bundletool build-apks \
  --bundle=app/build/outputs/bundle/release/app-release.aab \
  --output=app-release.apks \
  --ks=release.jks

Direct APK Distribution

# Rename for distribution
mv app/build/outputs/apk/release/app-release.apk \
   gozar-vpn-v{VERSION}.apk

# Generate checksum
sha256sum gozar-vpn-v{VERSION}.apk > gozar-vpn-v{VERSION}.apk.sha256

Testing & Validation

Pre-Release Testing

# Run unit tests
./gradlew test

# Run instrumented tests (requires connected device/emulator)
./gradlew connectedAndroidTest

# Run specific test class
./gradlew testDebugUnitTest --tests com.example.ExampleTest

# Generate test report
./gradlew testReport

APK Validation

# Check APK signing
jarsigner -verify -verbose -certs gozar-vpn-v{VERSION}.apk

# Analyze APK size
./gradlew analyzeApkSize

# Inspect APK contents
unzip -l gozar-vpn-v{VERSION}.apk

# Check with aapt
aapt dump badging gozar-vpn-v{VERSION}.apk

Device Testing

# Install debug APK on connected device
./gradlew installDebug

# Install release APK
adb install -r gozar-vpn-v{VERSION}.apk

# Launch app
adb shell am start -n com.example.gozarvpn/.MainActivity

# View logs
adb logcat | grep com.example.gozarvpn

# Uninstall app
adb uninstall com.example.gozarvpn

Troubleshooting

Common Build Issues

Gradle Sync Issues

# Clean and rebuild gradle cache
./gradlew clean
./gradlew build --refresh-dependencies

# Update Gradle wrapper
./gradlew wrapper --gradle-version=latest

Keystore Issues

# List keystore contents
keytool -list -v -keystore release.jks

# Create new keystore
keytool -genkey -v -keystore release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias gozar_vpn_key

# Check keystore password
keytool -list -keystore release.jks

Build Memory Issues

# Increase Gradle heap size (add to gradle.properties)
org.gradle.jvmargs=-Xmx2048m

# Or set environment variable
export GRADLE_OPTS="-Xmx2048m -XX:MaxPermSize=512m"

SDK/Dependencies Not Found

# List and install missing SDK components
$ANDROID_HOME/tools/bin/sdkmanager --list
$ANDROID_HOME/tools/bin/sdkmanager "build-tools;latest"
$ANDROID_HOME/tools/bin/sdkmanager "platforms;android-latest"

# Update all dependencies
./gradlew build --refresh-dependencies

Version Management

Update App Version

# Edit build.gradle (Module: app)
android {
    defaultConfig {
        versionCode X          # Increment by 1
        versionName "X.Y.Z"    # Use semantic versioning
    }
}

# Increment automatically with gradle
./gradlew -PversionCode=X -PversionName=X.Y.Z assembleRelease

Git Tag for Release

# Create version tag
git tag -a v{VERSION} -m "Release version {VERSION}"

# List tags
git tag -l

# Push tags to remote
git push origin v{VERSION}
git push origin --tags

# Show tag details
git show v{VERSION}

Security & Signing

Key Security Best Practices

# Store keystore securely (add to .gitignore)
echo "release.jks" >> .gitignore

# Backup keystore with encryption
gpg --symmetric --cipher-algo AES256 release.jks

# Verify key validity
keytool -list -v -keystore release.jks | grep -E "Owner:|Valid from"

Certificate Information

# Get certificate fingerprint (SHA256)
keytool -list -v -keystore release.jks | grep "SHA256:"

# Get certificate fingerprint (MD5)
keytool -list -v -keystore release.jks | grep "MD5:"

# Export certificate
keytool -export -alias gozar_vpn_key \
  -keystore release.jks \
  -file certificate.cer

Signing Configuration (build.gradle)

signingConfigs {
    release {
        keyStore file("path/to/release.jks")
        keyStorePassword System.getenv("KEYSTORE_PASSWORD")
        keyAlias System.getenv("KEY_ALIAS")
        keyPassword System.getenv("KEY_PASSWORD")
    }
}

buildTypes {
    release {
        signingConfig signingConfigs.release
    }
}

Useful Gradle Tasks Summary

Command Purpose
./gradlew assembleDebug Build debug APK
./gradlew assembleRelease Build release APK (unsigned)
./gradlew bundleRelease Build Android App Bundle
./gradlew clean Remove build artifacts
./gradlew build Build all variants
./gradlew test Run unit tests
./gradlew installDebug Install debug APK on device
./gradlew lint Run Android Lint analysis
./gradlew dependencies Show project dependencies
./gradlew tasks List all available tasks

Quick Checklist Before Release

  • Bump version code and version name in build.gradle
  • Update CHANGELOG.md with new features and fixes
  • Run ./gradlew test - all tests pass
  • Run ./gradlew lint - no critical issues
  • Build and test on multiple Android versions
  • Test on actual devices (not just emulator)
  • Verify app permissions are necessary
  • Check for security vulnerabilities
  • Sign APK with release keystore
  • Verify signature with jarsigner -verify
  • Create Git tag: git tag v{VERSION}
  • Update README with latest version
  • Test APK before uploading to Play Store

Additional Resources

Last Updated: 2025-12-21
Repository: ehssanehs/Gozar-vpn