Skip to content

Operator build walkthrough

This page takes you from a clean checkout to your own builds of the Android app and the Windows desktop player. Your panel key is baked in. Your colors and logos show on screen. Each step links to the reference page that explains it in depth: Client build, White-label branding, and Desktop player.

Build your own artifacts only if you want a branded product. If a generic app is fine, skip this page. The keyless public builds on the releases page connect to any panel — viewers just enter your panel key and account on the Connect screen.

0. What you need

  • Your panel public key. admin-cli init prints this when you set up the panel (see the operator guide). The key is public — it ships inside the build.
  • Node.js 24 and git — needed for both platforms' builds.
  • For the APK: JDK 17 and the Android SDK (build-tools, NDK, CMake). Client build lists the exact versions and environment variables. Windows, macOS, and Linux all work.
  • For the Windows exe: nothing extra. Electron and the packager come from npm.

1. One-time setup

git clone https://github.com/AbueloSimpson/aliran && cd aliran
npm install                                  # repo root (also covers desktop/)

cd client
npm install                                  # app dependencies
cd backend && npm install && cd ..           # P2P engine worklet dependencies
npm run bundle-backend                       # pack the engine -> backend/app.bundle.js
cd ..

Re-run bundle-backend every time you update the repo. The packed engine is a build artifact — it is not committed.

2. Your service descriptor

Everything brandable lives in one JSON file: the service descriptor (schema: client/config/service.example.json):

{
  "panelPubKey": "your 64-hex panel public key",
  "name": "Acme TV",
  "branding": {
    "logo": "https://acme.example/logo.png",
    "wallpaper": "https://acme.example/wall.jpg",
    "colors": { "primary": "#E11D48", "background": "#0B0B10", "accent": "#F59E0B" }
  }
}

branding.colors accepts the full token set (surface, text, focus, live, …) — see the descriptor reference in Client build. Omitted tokens fall back to the stock theme. Never put credentials in a descriptor you ship.

3. Custom Android APK

Two routes, depending on how far you want to go:

Route A — baked key, stock look. This is the fastest path to "our APK":

cd client
cp config/service.example.json config/service.json    # edit: your key + branding
rm -rf android/app/build/generated/assets/react       # descriptor changes aren't tracked by gradle
cd android && ./gradlew :app:assembleRelease -PreactNativeArchitectures=arm64-v8a
# -> client/android/app/build/outputs/apk/release/app-release.apk

Route B — fully branded. You get your own launcher icon, app name, splash logo, TV banner, and a co-installable applicationId. Make a brand directory and let the builder do the swapping:

cp -r client/brands/sunburst ../acme     # copy the example brand, keep it private
$EDITOR ../acme/service.json             # your key, name, colors
# replace icon.png (+ optional logo.png / wallpaper.png / banner.png)

node tools/brand.mjs ../acme
# -> client/android/app/build/outputs/apk/acme/release/app-acme-release.apk

See White-label branding for the brand-directory contract, the image sizes, and everything brand.mjs does.

Before distributing: release builds sign with the public React Native debug keystore by default. Generate your own keystore first and wire it into client/android/app/build.gradle (signing guide). One APK covers phones and Android TV, and it installs from Android 7. The P2P engine activates on Android 10+ and stays silent below — the app shows an "engine unavailable" notice there (see the client build guide).

4. Custom Windows exe

cd desktop
cp config/service.example.json config/service.json    # same descriptor contract
npm run build                                         # renderer bundle
npm run dist
# -> desktop/dist/Aliran Setup <v>.exe  +  Aliran-<v>-portable.exe
  • Your colors, name, logo, and wallpaper apply from the descriptor at runtime. You make no source edits. A brand directory's service.json drops in unchanged — use https URLs for logo/wallpaper, since Android drawable references don't exist here.
  • The installer icon and product name are the one manual step. Set them in desktop/electron-builder.yml.
  • Builds are unsigned unless you countersign with your own certificate. Desktop player §4 covers the SmartScreen reality and win.signtoolOptions.

5. Verify what you built

Install the APK (or run the exe) on a clean device/profile:

  1. It must boot straight to your branded splash and sign-in. An operator build never shows the Connect screen.
  2. Sign in with a viewer account from your panel. The lineup should appear, and a channel should play.
  3. Settings should show your service name and panel key. This is read-only — a baked key is not changeable at runtime.

If you see the Connect screen instead, the build was packaged without config/service.json. That is the public flavor.