No description
  • Shell 64%
  • Python 28.3%
  • Dockerfile 7.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-02 23:23:26 -07:00
.dockerignore Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
.gitattributes Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
.gitignore Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
builder.sh Fix builder.sh 2026-11-02 23:23:26 -07:00
docker-compose.example.yml Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
Dockerfile Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
patch_android.py Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00
README.md Create tool to auto build custom screentinker apks with hardcoded server url. 2026-11-02 22:04:13 -07:00

screentinker-apk-builder

A Docker image that builds the ScreenTinker Android player with your server URL baked in. It publishes the APK where your ScreenTinker server serves OTA updates from (/data/ScreenTinker.apk). Then it keeps the APK current.

How it works

  1. Clone upstream (or your fork) and check out the newest release tag, or the tip of a branch.
  2. Patch the app (patch_android.py) so it uses SERVER_URL:
    • Locked (LOCK_SERVER_URL=true, default): the setup screen shows the URL read-only and connects automatically. MDM provisioning extras and the dashboard's remote set_server_url command can't point the player anywhere else.
    • Default only (LOCK_SERVER_URL=false): the URL is pre-filled on first run but can still be changed.
  3. Build and sign it with your keystore. The build adds a v1 signature too, the same way upstream release builds do. It then checks the signature and the version.
  4. Write the result to the server's data volume. The write is atomic, so the server never serves a half-written file. The server notices the new file on its own, and players pick it up on their next update check (every 30 minutes).

Every patch is anchored on exact upstream code. If upstream refactors that code, the build fails loudly instead of shipping an APK that ignores your URL. The previously published APK stays in place.

Auto-updating

Variable Default
BUILD_ON_START true Always build when the container starts.
CHECK_INTERVAL 1h Poll upstream with git ls-remote and rebuild only if the tracked tag/commit (or this container's config) changed. 0 = off.
REBUILD_INTERVAL 0 Also rebuild unconditionally on a timer (e.g. 7d). 0 = off.
RETRY_FAILED_INTERVAL 6h How long to wait before the change-check retries a target that failed to build.

Intervals accept s, m, h and d suffixes, e.g. 90s, 15m, 6h or 1d. If both CHECK_INTERVAL and REBUILD_INTERVAL are 0, the container builds once and exits. That suits restart: "no" or a cron job.

A target that fails to build isn't retried on every poll. It's retried after RETRY_FAILED_INTERVAL, which covers transient network or Gradle failures. It's also retried sooner when upstream moves on, the config changes, or on the next REBUILD_INTERVAL or container restart.

Versioning

Two version rules matter here. The server offers an update only when the APK's versionName is newer than the player's. Android refuses an install whose versionCode is lower than the installed one.

TRACK versionName versionCode
release (default) the tag, e.g. 3.1.2 commits in history + VERSION_CODE_OFFSET
branch <VERSION>-patch<commit count>, e.g. 3.1.2-patch2116 same

The server's OTA logic treats -patchN as a release and compares N numerically. That means every new commit on the branch is offered as an upgrade.

Switching an existing fleet from release to branch on the same core version goes "backwards": 3.1.2-patch2116 sorts below 3.1.2. The new build only reaches devices after the next upstream version bump, or after you uninstall and reinstall the app.

Signing key - read this

  • On first start, a key is generated in the /keys volume (release-key.jks + keystore.env). Back it up. OTA only installs APKs signed with the same key as the installed app. If you lose the key, every device needs a manual uninstall and reinstall.
  • To use your own key, put it at /keys/release-key.jks and set KEYSTORE_PASSWORD, KEY_PASSWORD and KEY_ALIAS. See the quick guide below.
  • Devices running the official ScreenTinker APK use a different key. They can't upgrade to this build over OTA, and Android won't install it over the top. Uninstall the official app once, then install yours from https://<your-server>/download/apk. Every update after that arrives automatically.

Quick guide: bring your own keystore

  1. Generate a keystore (skip this if you already have one):

    keytool -genkeypair -keystore release-key.jks -storetype PKCS12 \
      -alias myplayer -keyalg RSA -keysize 4096 -validity 36500 \
      -dname "CN=My ScreenTinker Player"
    

    You'll be prompted for a password. PKCS12 keystores use one password for both the store and the key. No keytool on hand? The image has it, and running it via compose mounts the /keys volume, so you can generate straight into place (and skip step 2):

    docker compose run --rm --entrypoint keytool apk-builder \
      -genkeypair -keystore /keys/release-key.jks -storetype PKCS12 \
      -alias myplayer -keyalg RSA -keysize 4096 -validity 36500 \
      -dname "CN=My ScreenTinker Player"
    
  2. Put it where the builder looks. The easiest way is to bind-mount a host directory as /keys instead of the named volume:

    volumes:
      - ./keys:/keys          # instead of apk-keys:/keys
    

    Then drop the file in as ./keys/release-key.jks. (With a named volume you'd copy it in with docker compose cp release-key.jks apk-builder:/keys/ after the container exists.)

  3. Tell the builder how to open it, either via environment variables in the compose file:

    environment:
      KEYSTORE_PASSWORD: "your-store-password"
      KEY_PASSWORD: "your-key-password"     # omit if same as KEYSTORE_PASSWORD
      KEY_ALIAS: "myplayer"
    

    ...or, to keep the password out of the compose file, as /keys/keystore.env next to the keystore (chmod 600 it):

    KEYSTORE_PASSWORD=your-store-password
    KEY_PASSWORD=your-key-password
    KEY_ALIAS=myplayer
    
  4. Start the container. At startup it verifies it can open the alias with the configured password and fails loudly if it can't. Use a different filename or location with KEYSTORE_FILE / KEYSTORE_DIR, and set AUTO_GENERATE_KEYSTORE=false if you'd rather fail than silently generate a new key when the file is missing (e.g. a forgotten mount).

Switching an already-deployed fleet to a different key has the same cost as losing the key: OTA won't cross signing keys, so each device needs a one-time uninstall and reinstall.

Usage

cp docker-compose.example.yml docker-compose.yml   # set SERVER_URL and the volume name
docker compose up -d --build
docker compose logs -f apk-builder

Or add the apk-builder service to the compose file that already runs ScreenTinker, and share the server's /data volume directly. The first build downloads Gradle and its dependencies, which takes several minutes. Later builds reuse the cache in /state. Allow about 4 GB of RAM for Gradle.

The server must have OTA enabled. That's the default; it's turned off by OTA_ENABLED=false or the per-device OTA setting.

All settings

Variable Default
SERVER_URL (required) http(s)://host[:port][/path] the players connect to.
LOCK_SERVER_URL true See How it works.
REPO_URL upstream GitHub Use your fork if you carry your own changes.
TRACK release release or branch.
BRANCH main Branch to follow when TRACK=branch.
INCLUDE_PRERELEASES false With TRACK=release, also consider tags like v3.2.0-beta1.
OUTPUT_DIR /data Mount the server's data volume here.
OUTPUT_NAME ScreenTinker.apk ScreenTinker-beta.apk feeds the server's per-display beta channel instead.
WRITE_VERSION_SIDECAR true Also write <OUTPUT_NAME>.version, which the server uses as a fallback.
VERSION_CODE_OFFSET 0 Added to the commit-count versionCode, e.g. if you previously shipped higher codes.
KEYSTORE_DIR / KEYSTORE_FILE /keys / release-key.jks
KEY_ALIAS remotedisplay
KEYSTORE_PASSWORD / KEY_PASSWORD from keystore.env Required only for a keystore you supply.
AUTO_GENERATE_KEYSTORE true Generate a key if none exists.
STATE_DIR /state Clone, Gradle cache, last-build record.