Welcome to WitVPN

What you get

How long & how much?

1. Prerequisites

Install these first. The setup script will verify them and guide you if anything is missing.

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js 20
brew install node@20

# JDK 17
brew install --cask temurin@17

# Android Studio (~8GB)
brew install --cask android-studio

# (Optional) Firebase CLI — only for deploy
npm install -g firebase-tools

npm install -g firebase-tools   # optional, for deploy

# Node.js 20 (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# JDK 17
sudo apt install -y openjdk-17-jdk

# Android Studio — download from https://developer.android.com/studio
# Extract to ~/android-studio and run bin/studio.sh

# (Optional) Firebase CLI
sudo npm install -g firebase-tools

Verify installation

node -v      # expect v18+ (v20+ preferred)
npm -v       # expect 9+
java -version # expect 17
# Android Studio: launch it once to finish SDK setup

2. Create your Firebase project

One Firebase project is shared by both apps. Go to console.firebase.google.com and follow the steps.

4

Register the Android app

Project Settings (gear icon) → General tab → Your apps → Android icon.

• Package name: com.wit.witvpn (or your own — remember what you entered)
• App nickname: anything
• SHA-1: you can add this later after generating your keystore

Click Register app → Download google-services.json. Save it somewhere you'll find later.

console.firebase.google.com/.../settings/general

After clicking Register, you'll be prompted to download google-services.json — drop it into 01-android-app/app/:

console.firebase.google.com/.../settings/general

5

Register the Web app (for the Admin Dashboard)

Same screen → Add app → Web (</> icon) → nickname it → Register app.

Firebase shows you a config object with 7 values:

const firebaseConfig = {
  apiKey: "AIza...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123...",
  appId: "1:123:web:abc...",
  measurementId: "G-..."      // optional
};

Keep this tab open — you'll paste these values into the Admin setup script.

console.firebase.google.com/.../settings/general

After registering, the SDK config values appear:

console.firebase.google.com/.../settings/general

3. Spin up an OpenVPN server

Your Android app needs at least one OpenVPN server to connect to. The bundled angristan/openvpn-install script (MIT, in 03-vpn-server/) takes a fresh Linux VPS and turns it into a working server in 5 minutes.

# from your laptop
scp 03-vpn-server/openvpn-install.sh root@YOUR_VPS_IP:/root/

# then SSH in
ssh root@YOUR_VPS_IP
chmod +x openvpn-install.sh
./openvpn-install.sh

scp root@YOUR_VPS_IP:/root/default.ovpn .

Full reference + troubleshooting: 03-vpn-server/SETUP.md.

4. Set up the Android app

Open a terminal in the extracted package root.

cd 01-android-app
bash setup.sh --build
# Windows: double-click setup.bat, or run `setup.bat` from cmd

The script will:

1. Check Node, JDK 17, Android SDK — and guide you to install anything missing.
2. Ask you to place google-services.json at app/google-services.json (from Firebase Step 4).
3. Prompt for: Firebase Android config, Google Web Client ID, AdMob App ID + ad unit IDs, Play License Key, Envato purchase code (optional).
4. Generate a release keystore (3 short questions — see below).
5. Run ./gradlew bundleRelease — output: app/build/outputs/bundle/release/app-release.aab.

5. Set up the Admin Dashboard

cd 02-admin-dashboard
bash setup.sh --dev
# Windows: setup.bat

The script will:

1. Check Node & npm.
2. Prompt for your Firebase Web SDK config (from Firebase Step 5 — not the Android one!).
3. Write .env and .firebaserc.
4. Ask you to place serviceAccountKey.json at the project root (from Firebase Step 6).
5. Run npm install.
6. Start the Vite dev server at http://localhost:5173.

6. Create your first admin user

After you've signed into the dashboard once with Google (so Firebase Auth has your UID), run:

cd 02-admin-dashboard
npx tsx scripts/setAdminRole.ts your@email.com

This sets a admin: true custom claim on your user. Sign out of the dashboard and back in — admin-only routes unlock.

7. Populate Firestore

The Android app reads Servers and configs from Firestore. Easiest path: use the Admin Dashboard UI — open Servers → Add Server, fill in country/IP/premium flag, then upload the .ovpn file you got from Step 3. The dashboard base64-encodes it for you.

Below is what the same data looks like inside Firebase Console, in case you want to seed it manually before the dashboard is up.

console.firebase.google.com/.../firestore/data

Create the configs collection

Click Start collection at the root of the database, set Collection ID to configs:

console.firebase.google.com/.../firestore

Inside the document, add an ads array of maps. Each map has a google sub-map with your AdMob IDs:

console.firebase.google.com/.../firestore/configs

Then add the iap map with your subscription product IDs from Play Console:

console.firebase.google.com/.../firestore/configs

Composite index for Servers

The Android app filters Servers by status + premium simultaneously, which Firestore needs an index for. Go to Indexes tab → Add index:

console.firebase.google.com/.../firestore/indexes

Collection ID: Servers · Fields: status Ascending, premium Ascending · Query scope: Collection. Save and wait ~1 minute for the index to build.

Required fields — Servers collection

8. Deploy

Android app → Google Play Store

1. Log in to play.google.com/console ($25 one-time if first time).
2. Create a new app → choose defaults → fill required policy questionnaires.
3. Release → Production → Create new release → upload app-release.aab.
4. Fill store listing (icon, screenshots, description, privacy policy URL).
5. Submit for review. First review is 1–7 days.

Admin Dashboard → Firebase Hosting

cd 02-admin-dashboard
firebase login              # first time only
npm run build
firebase deploy --only hosting
# optional — only needed for the onAdminCreated trigger
firebase deploy --only functions

The firebase.json shipped in 02-admin-dashboard/ already wires up build/ as the public directory and rewrites all routes to index.html (SPA mode):

02-admin-dashboard/firebase.json

You normally don't need to edit it. If you do, change "public" to match your build output folder, or add custom "headers" for caching.

FAQ

For the full FAQ see FAQ.md. Quick answers below.

Troubleshooting

Licensing

Android app + Admin Dashboard — your CodeCanyon Regular License (single end-product) or Extended License (reusable across multiple end-products). Full terms at themeforest.net/licenses.

Bundled OpenVPN (01-android-app/ovpn/) — GPL-2.0. Mere aggregation in a closed-source app is allowed (this is standard for commercial VPNs). If you modify files inside the ovpn/ folder, those modifications must be available under GPL-2.0 on request. If you don't modify ovpn/, you have nothing extra to do.

Full license text: see 01-android-app/LICENSE and 02-admin-dashboard/LICENSE.

Support

Best channel is the CodeCanyon item comments page — replies within 24h on business days.

Please include:

• Your item order number (from the Envato receipt email)
• A screenshot of the error
• Which step you were on (link to this page's section, e.g. #android)
• Your OS + node -v + java -version output

Need custom work? Contact via the Envato profile on the item listing.

WitVPN CodeCanyon Package v4.1.4 · README · INSTALL · FAQ