Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
Server Release And Recovery
This file owns routine immutable Server releases. Initial service setup is
in self-hosting operations; environment and ports
are in configuration reference. Exact production
identity is owned by the immutable release descriptor, runtime REVISION, and
deployment record. Status owns only the compact current product
and operational snapshot; it is not a per-release ledger.
The tracked release-server.sh updates an existing Go deployment with embedded
media, bare-metal nginx, nftables, and application port 8787. It requires an
existing running Go release. Another proxy, firewall owner, application port,
first installation, or initial embedded-media cutover needs its own scoped
bootstrap/updater; do not call this wrapper generic.
Its firewall check compares the nftables ruleset without traffic counters; it
does not depend on a particular table name. Coordinate other firewall writers
outside the cutover window. See nft output options.
Release Boundary
A routine Server release changes only the built Piik server binary and the Browser assets it embeds. It does not change infrastructure, service units, proxy/firewall rules, secrets, media listener configuration, or persistent room state.
Any task that touches one of those excluded surfaces must first record its exact pre-change value and a recovery procedure for that surface. Do not complicate the routine Server wrapper with one-off infrastructure branches.
The pre-cutover Server release is guaranteed only through bounded health and postflight. It has no retention contract afterward and is not a maintained backup; Git and immutable artifacts own history.
Build Host
Start from a clean exact revision using Node from .node-version,
npm from package.json, and Go from go.mod:
npm ci
npm run check
node scripts/package-server-release.mjs <output-directory-outside-repository>
The packager refuses a dirty tree, builds the Browser assets and the
linux/amd64 server binary (or linux/arm64 with --arch arm64) from that exact revision without cgo, records the
full revision, emits a runtime archive plus path/size/SHA-256 manifest and release descriptor, and
extracts its own artifact to verify it. The archive contains exactly
piik-server, LICENSE, THIRD-PARTY-NOTICES.txt, and REVISION. Upload
the archive, manifest, and descriptor together to /opt/piik/uploads.
ARM64 file names include -linux-arm64 after the revision; x64 names stay
unchanged. The deployment wrapper rejects a package for another host architecture.
--os windows --arch amd64 packages the same Server core as
piik-<revision>-windows-amd64-runtime.zip, with piik-server.exe in place of the
Linux executable. It uses the same descriptor and checksum inventory; containers
and release-server.sh remain Linux-only. Windows operation follows the
self-hosting guide.
Public Release pages expose the runnable packages and put package checksums in the release body. Retain the original complete build output outside the checkout for later managed deployment or mirror retries: descriptors and manifests are available in CI artifacts for 14 days and are not public Release attachments. Do not rebuild an existing published version to replace missing metadata or bytes.
The same Server descriptor is also the App assembly input. On each target platform, provide that platform's Go toolchain:
PIIK_GO=/path/to/go node scripts/assemble-app.mjs \
/outside/repository/server-release/piik-<revision>.release.json \
/outside/repository/piik-app \
--target windows-amd64 \
--capture /path/to/platform-capture \
--tunnel /path/to/cloudflared
Assembly refuses a dirty or different revision and emits one directory with the
App executable, the Browser assets taken from that release and embedded in
it, the selected sidecars, notices, and matching REVISION. Its required target
is one of windows-amd64, linux-amd64, linux-arm64, darwin-arm64 or darwin-amd64; every supplied
binary input must match it. It does not create an installer, auto-updater,
release tag, or compatibility bundle.
Darwin App assembly runs on macOS with its SDK and cgo enabled: the pinned LiveKit dependency's Darwin CPU statistics call Mach APIs. Windows and Linux App builds keep cgo disabled. A core check on those hosts explicitly skips the Darwin binaries; macOS build and package verification belong to the existing native runner. Server builds for both Linux architectures remain cgo-free.
The platform package also carries its native presentation metadata: Windows
embeds the icon in the Go executable, Linux emits a freedesktop desktop entry
under share/, and macOS emits a self-contained .app with an ICNS resource.
The macOS CFBundleExecutable names the real Mach-O App binary in
Contents/MacOS; its relative runtime/, license notices and REVISION live
beside it. Moving the .app must retain every runtime dependency. This follows
Apple's bundle relocation guidance
and avoids a shell entry that reaches outside the bundle. Package checks execute
the extracted entry and helpers; Finder/Gatekeeper and desktop permissions still
need macOS acceptance.
CI and local release-candidate builds use the same wrapper on the target's native operating system:
node scripts/package-app-candidate.mjs \
/outside/repository/server-release \
windows-amd64 \
/outside/repository/app-candidate
The wrapper downloads the pinned public-link sidecar, verifies its digest,
builds the target App and available capture process, executes every packaged
runtime from the extracted ZIP, and emits one .zip plus its SHA-256 file.
App ZIPs use ordinary Store/Deflate compression and relative entry names without
. or .. path segments; include hidden files and preserve executable modes on
Unix. Windows packaging also checks every entry through Windows Explorer's ZIP
reader. A successful extraction by the writer's own library does not establish
compatibility with the user's default archive tool.
Retain the descriptor and successful deployment output as release metadata. Do not create a follow-up source commit solely to duplicate their revision, asset, or hashes.
Manual app_checks=true dispatch packages both Server architectures and all App
candidates after validation. Once automatic publication
is explicitly enabled, accepted main merges run that same pipeline and publish
the verified artifacts. Candidate artifacts are retained for 14 days. Ordinary
branch pushes stay quiet; PRs run only the read-only release-note check. No
release-record commit is written back to main.
The workflow does not deploy into a running application service.
Do not build or run the full repository check on a constrained production host. That host runs only the packaged binary and needs no Node, npm, or dependency install.
Update Check
Builds carry a product version plus full source revision. Packagers use one
release plan or exact Git tag and inject its identity into Server, App and Web;
untagged local candidates use development. Schema-2 package descriptors carry
the same pair and artifact hashes. The version policy
owns ordering and first-public-release readiness.
The default App launcher starts immediately, then checks GitHub Releases in the background. Published binaries still fall back to Gitee if GitHub is unavailable; current manual downloads use AtomGit. The release-source policy owns selection and provenance checks. It shows a link only when the latest stable release is newer, the same version has a known different source SHA, or a development build can choose the official release. These notices are distinct; a different SHA alone is not called newer. The request sends no current revision, credentials, room data, or media data; network errors, private-repository responses, and missing releases are treated as no notice. Checking does not download an archive, replace files, or interrupt a running share; the user can follow the update link to download the App ZIP.
An operator can perform the corresponding read-only Server check:
bash deploy/check-release.sh
The Server also checks once in the background after startup and logs an available release with its download URL. It does not delay startup, periodically poll, notify room participants or install anything.
The script runs the deployed binary's --check-release, using that binary's
injected identity, and prints one JSON result with versions, available source
SHAs and the release URL. Exit 0 means no newer/different official build,
10 means update-available, different-build or official-release, and 20
means the check is unavailable. It does not accept a separate revision file.
For a private repository, inject a short-lived GITHUB_TOKEN
through the operator environment; never place it in the repository or command
line. The command does not mutate files, services, containers, or persistent
state.
Atomic Cutover
The wrapper requires an already running packaged Go release and the service layout described above. For a new installation, use the self-hosting guide. Infrastructure changes need their own scoped recovery procedure under CONTRIBUTING.
Run the tracked server entry with the uploaded descriptor:
sudo env PIIK_PUBLIC_ORIGIN=https://share.example.com \
bash /path/to/repository/deploy/release-server.sh \
/opt/piik/uploads/piik-<revision>.release.json
The wrapper:
- takes a deployment lock and validates the descriptor, revision, archive, manifest, current Go process, Piik/nginx service state, and public origin;
- rejects unexpected archive paths, links, file types, or duplicate inodes;
- extracts to a new release directory and verifies every file hash and size;
- validates production configuration by running the packaged binary's configuration check as the service user under a bounded runtime;
- proves the old and new releases share no regular-file inode;
- atomically switches
/opt/piik/current, starts the service, and polls bounded local/public health; and - restores the exact prior symlink and service when cutover or health fails.
Never hard-link release files or recursively mutate permissions before the
inode audit: metadata changes would violate both releases. Expected service
states should be read as data (systemctl show), not used as bare commands under
strict-shell error traps.
Persistent State
Stable mode stores only room authority at the configured SQLite path. The systemd service owns its state directory and file permissions. Application restart retains room ownership, invitations, policy and password verifier; participants, signaling, routes, SFU state and media reconnect from fresh process state.
Lightweight mode has no persistent room state and starts empty. A release does not add a migration or compatibility reader for either mode; current exact schema validation fails closed before accepting signaling or media admission.
Postflight
Verify only the surfaces relevant to the release:
- local and public
/healthzreturn{"status":"ok"}; - the public HTML references the new immutable main asset;
- Piik and nginx have expected active/restart state;
- Piik owns each configured STUN/SFU UDP listener and public reachability matches the configuration;
- the current symlink and served revision match the descriptor;
- room creation, Host authentication, one direct Viewer, and configured SFU fallback complete the scoped smoke; and
- infrastructure, config, secrets, ports, and persistent state not named by the task are unchanged.
Representative network, mobile, audio, 20-Viewer, and endurance evidence belongs to verification status, not routine postflight.
Recovery
Before cutover, the wrapper keeps the exact prior release path. On failure after the switch begins, it stops Piik, restores that path atomically, restarts the service, and waits for health. A failed recovery exits distinctly and requires operator intervention; it must not silently report the new release as active.
Infrastructure or persistent-state recovery is separate and limited to the surfaces changed by that task. Do not restore an entire server, old firewall, or old secret set for an application-only failure.
If a task changes persistent room data, prepare and verify a separate SQLite backup and recover matching data, configuration and application together. Restoring old data can revive revoked credentials; account for later authority changes before reopening ingress.