- Shell 64%
- Python 28.3%
- Dockerfile 7.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .dockerignore | ||
| .gitattributes | ||
| .gitignore | ||
| builder.sh | ||
| docker-compose.example.yml | ||
| Dockerfile | ||
| patch_android.py | ||
| README.md | ||
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
- Clone upstream (or your fork) and check out the newest release tag, or the tip of a branch.
- Patch the app (
patch_android.py) so it usesSERVER_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 remoteset_server_urlcommand 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.
- Locked (
- 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.
- 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
releasetobranchon the same core version goes "backwards":3.1.2-patch2116sorts below3.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
/keysvolume (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.jksand setKEYSTORE_PASSWORD,KEY_PASSWORDandKEY_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
-
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
keytoolon hand? The image has it, and running it via compose mounts the/keysvolume, 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" -
Put it where the builder looks. The easiest way is to bind-mount a host directory as
/keysinstead of the named volume:volumes: - ./keys:/keys # instead of apk-keys:/keysThen drop the file in as
./keys/release-key.jks. (With a named volume you'd copy it in withdocker compose cp release-key.jks apk-builder:/keys/after the container exists.) -
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.envnext to the keystore (chmod 600it):KEYSTORE_PASSWORD=your-store-password KEY_PASSWORD=your-key-password KEY_ALIAS=myplayer -
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 setAUTO_GENERATE_KEYSTORE=falseif 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. |