Skip to content

armgit / Piik

Public Imported from GitHub
0

Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。

23.0 KB
Raw Blame

Configuration And Ports

The tracked .env.example is the executable schema companion; internal/server/config is validation truth. Keep real values in the service secret store or an untracked access-restricted environment file.

Ownership

  • Deployment configuration owns listeners, advertised origins, persistence, admission, capacity and optional services. Change it before starting the process.
  • The Host owns share settings and the available per-share route switches in the shared Web UI. Server and App use the same controls, order and semantics; configuration changes availability, not which controls exist. A fixed switch remains visible and explains the reason in text or its pure-visual hint.
  • Protocol versions, queue bounds and routing/adaptation constants stay in code. They are not deployment tuning knobs. Debug and report destinations are explicit diagnostic options, not normal share settings.

Application Environment

Variable Contract
PIIK_ENV development or production, default development; set production for server deployments to enable production validation and Secure site-access cookies for configured HTTPS destinations.
LISTEN_HOST Defaults to 0.0.0.0; bare-metal production normally uses 127.0.0.1.
PORT Positive TCP port, default 8787; the tracked release wrapper supports only that default.
PUBLIC_BASE_URL Exact public HTTP(S) origin; production requires HTTPS.
ALLOWED_ORIGINS Unset or empty follows PUBLIC_BASE_URL. A non-empty comma-separated list replaces that default; include every trusted browser origin (scheme, host and port). Wildcard is invalid.
TLS_SELF_SIGNED Optional direct HTTPS, default false. true generates an in-memory certificate for the exact PUBLIC_BASE_URL host; it changes on restart and requires browser confirmation. Requires an HTTPS public origin; cannot combine with certificate files.
TLS_CERT_FILE / TLS_KEY_FILE Optional PEM certificate chain and private key, configured together. Direct HTTPS uses the existing LISTEN_HOST/PORT. Startup and --check-config validate the pair, host and validity dates. Files are read at startup; renewal and restart remain the operator's responsibility.
SITE_ACCESS_PASSWORD Optional in every environment. Unset or empty allows entry without a site password. A configured value is matched exactly, including spaces and Unicode; there are no password length or character rules. General HTTP request limits still apply. Room ownership and Viewer admission remain independent.
ROOM_DATABASE_PATH Hosted defaults to rooms.sqlite in its working directory when unset or blank. An explicit absolute file path selects another SQLite file; :memory: opts into process-memory room authority. App Local remains in memory.
ROOM_EMPTY_TIMEOUT_SECONDS Integer 0..31536000, default 0 (disabled). Positive values enable empty-room expiry and oldest-empty reclamation under allocation pressure. Apply at Server startup; App Local retains its process-only lifecycle.
MAX_VIEWERS_PER_ROOM 1..20, default 20; excludes the Host.
ENDPOINT_MEDIA_COPY_CAPACITY Shared endpoint steady-copy cap 1..3, default 2.
STUN_URLS Comma-separated advertised stun: discovery URLs; at least one is required in production. These are not local bind addresses and may use an unproxied DNS name separate from the Web origin.
STUN_LISTEN_HOST Hosted IPv4 STUN bind address, default 0.0.0.0 when STUN_URLS is configured; independent of HTTP LISTEN_HOST. App Local configuration owns its separate LAN endpoint below.
NAT_PREDICTION_ENABLED Optional bounded NAT prediction capability, default false; requires an ordinary STUN_URLS endpoint on UDP 3478. Hosted startup binds UDP 3479/3480 before advertising the capability. Current pages use it automatically on P2P-first sites; ordinary ICE remains available without it. Firewall reachability remains an operator requirement.

Room capacity

MAX_VIEWERS_PER_ROOM counts authenticated Viewers per room, excluding the Host. Self-hosted Server accepts 1..20 and defaults to 20, matching the App and deployment examples. Apply changes by restarting the Server (with Compose, run docker compose up -d to recreate it after editing .env). Restart interrupts active connections; excess Viewers receive ROOM_FULL when joining again. App Local and public-invite modes stay fixed at 20.

Values above 20 are rejected at startup. This is also a wire-contract bound, so increasing it in source requires a compatibility and capacity review. More Viewers can add relay hops, routing wait and total media load. The setting does not increase the per-endpoint copy cap or guarantee available bandwidth.

Room retention

Public sites can use ROOM_EMPTY_TIMEOUT_SECONDS=3600 to release unused codes. Only rooms without authenticated participants expire; watching, paused sharing and idle chat are protected. When all codes are used, the oldest empty room may be reclaimed before the hour. Expired rooms and invitations must be recreated. The default 0 preserves existing indefinite-room behavior. The complete lifecycle and restart semantics belong to rooms/access.

Media fallback

Automatic SFU fallback runs inside the Hosted process when SFU_UDP_PORT is set:

Variable Contract
SFU_UDP_PORT Optional UDP media port 1..65535; unset or blank disables SFU and fixes Privacy mode on for every room. Set 7882 for the standard public listener and allow the Host to choose Privacy mode.
SFU_LISTEN_HOST IPv4 bind address, default 0.0.0.0; independent of HTTP LISTEN_HOST. Read only when SFU is enabled.
SFU_PUBLIC_IP Optional advertised IPv4 address or DNS hostname for a host behind NAT. A hostname resolves at startup and every minute; new media connections use the latest successful IPv4 result without restarting Piik. Forward the same UDP port as SFU_UDP_PORT. Read only when SFU is enabled.
SFU_ONLY false by default. true requires SFU_UDP_PORT and sends every room through SFU, without Peer candidates or background P2P convergence. Applies after Server restart.

SFU control uses the application's authenticated signaling connection. No separate control origin or infrastructure credentials are configured. Local and public-link App construction create no SFU listener. The relay does not provide application E2EE.

For a P2P-only Server, leave SFU_UDP_PORT blank. Room authority, signaling, configured STUN and peer relays remain; no media-server fallback is possible. The server enforces this even if a Host requests hybrid mode. There is no separate SFU_ENABLED flag to conflict with the listener configuration.

With SFU_ONLY=true, the page shows a locked Server media policy in place of P2P settings. An older page requesting Privacy mode is refused before sharing; refresh it or turn Privacy mode off. Capacity exhaustion and connection failure use the existing bounded SFU admission/recovery path, never a P2P escape. This policy needs sufficient server bandwidth and a working UDP route; it is not a TURN/TCP fallback. App Local/public-link and the public Demo remain P2P-only.

The SQLite parent directory must exist and be writable. The systemd template sets /var/lib/piik/rooms.sqlite under its managed state directory; the container image sets /home/nonroot/rooms.sqlite under its writable data directory. Keep the existing database path and data across application updates. Room authority has no idle expiry by default; the separate site-access cookie keeps its 24-hour idle lifetime within one service run. Restarting the App or Server requires site-password entry again; saved rooms and invitation grants are restored.

Removed access, room TTL/lease, endpoint-tier, room-rollout, and TURN variables fail startup even when blank. A present NODE_ENV fails the same way, so a stale environment file cannot silently drop a deployment out of production. The private deployment uses its scoped atomic updater. Supported public upgrades and any compatibility handling follow the active versioning contract.

Piik App Configuration

Piik App stores Piik/client.json under the operating system's user configuration directory (%APPDATA% on Windows, ~/Library/Application Support on macOS, and $XDG_CONFIG_HOME or ~/.config on Linux). The App manages its version schema field. The user settings are:

Setting Contract
site / sites The first approved Piik Site origin and optional additional origins. Local confirmation or explicit --site adds approval without replacing other sites; the launcher revokes each independently. Existing single-site configuration remains valid.
localAccessPassword Empty by default. Optional password for the App's Local room authority, with the same exact-match behavior as SITE_ACCESS_PASSWORD. It is separate from a hosted site's password.

Before rolling back to an App that supports only one approved Site, revoke all but one Site in the current launcher. This removes the additional sites field that older Apps cannot read, while preserving the remaining approval and password.

For public invitations, the optional PIIK_STUN_URLS environment variable replaces all built-in STUN destinations. It accepts a comma-separated list of up to six stun: URLs, using the Server's URL validation. With three or more destinations, the second and third also supply NAT prediction observations; one or two use ordinary ICE only. Empty or unset retains the defaults. Local LAN mode ignores this setting, and an approved Site supplies its own ICE configuration. No settings panel or additional media transport is involved.

LAN mode retains the Host's HTTP loopback entry and serves HTTPS on the selected LAN IPv4 address at the same TCP port. Both listeners share one HTTP server, room authority and shutdown owner. Its self-signed certificate and private key live only in memory for that run; the App terminal displays the SHA-256 fingerprint for manual confirmation. No CA is installed and no TLS files are saved. The selected LAN address also runs the existing Binding-only STUN service on the App's numeric UDP port (default 8787). This lets Browsers discover usable addresses on routed virtual LANs without relying on multicast name discovery or contacting a public STUN service. HTTP and STUN have one application startup/shutdown owner; public-link mode does not bind this LAN endpoint. Allow Piik through the firewall on the selected network for both TCP and UDP; STUN carries address discovery, not shared media.

For example, in PowerShell, set $env:PIIK_STUN_URLS = 'stun:your-stun.example:3478' before running ./piik-app.exe. Use a service you trust: STUN sees participants' public network addresses, but does not receive shared media.

The Site's App button requests local confirmation for the page's exact origin. The --site automation input defaults to HTTPS when the scheme is omitted; explicit HTTP or HTTPS is preserved. Both save the normalized origin and reject credentials, room paths, queries and fragments. The App does not probe protocols or downgrade a failed HTTPS connection to HTTP.

The launcher remembers the last mode confirmed with the launch button. This optional preference lives beside the configuration as client.json.mode (or <custom-config-path>.mode); removing it restores the initial selection without changing saved settings. Without a valid Local/Public preference, the public invitation link is selected. Choosing a mode does not start it until confirmed. Local mode remains available for the same network. The star beside an approved Site selects it as the next ordinary startup page. This preference lives in <config-path>.startup-site, separately from access permission. Only one approved origin opens automatically; revoking that origin clears the star, while approving or revoking other sites leaves it intact. Unstarring restores launcher entry, and explicit CLI mode flags retain precedence. Selecting Local or Public Link, including through the CLI, preserves the saved Sites and their allowed App origins; only local approval/revocation or --site changes them. A Site can use native capabilities while the App waits in its launcher; it does not need a Local room service. For Local mode, the launcher selects a sole active address or sole private IPv4 address automatically. With several choices it shows interface names and IPs; an ambiguous choice must be selected before launch. --lan-address preselects an active address. Selection applies to this launch and is revalidated at startup. It sets the local HTTPS listener and invitation origin; the Host keeps its HTTP loopback entry and ICE remains free to use available media interfaces. Public Link and use through an approved Site require no local address selection.

Command-line options select entry and local runtime behavior:

Option Purpose
--site <origin> / --local Save and use a Site, or select the self-contained Local mode. Mutually exclusive.
--link Create a public Viewer invitation for Local mode.
--config <path> Select another App configuration file.
--lan-address <IPv4> / --port <port> Override the Local invitation address or web port (default 8787).
--capture-process <path> / --tunnel-process <path> Override packaged native capture or public tunnel helpers. Ordinary installations use the packaged paths.
--debug / --log-dir <path> Enable diagnostics or choose their destination as described below.

Share quality, room access policy, language and theme are configured in the shared Web UI. Decorative motion follows the system's reduced-motion preference. App-wide picture/audio quality preferences use <config-path>.quality; removing that optional file resets them on the next App launch. It contains no device or room credentials. The media owner defines when preferences apply; older Apps ignore the file and keep reading client.json.

Diagnostics

Normal Server logs record startup identity, listener and enabled services, unexpected failures, orderly shutdown and any available release found by the single background startup check. Detailed room/ICE/media traces require Debug.

Diagnostics are local and opt-in. Enable them before reproducing the problem:

Surface Enable Export
App Enable Debug launch with the small chip icon after the theme control in the mode selector, or start with --debug / PIIK_DEBUG=client Press D in the terminal for a ZIP
Browser Host/Viewer Open Help → Debug after the theme control and confirm the reload, or add ?debug=1 before any invitation fragment Help → Web report downloads the browser report
Hosted Server Start with --debug, PIIK_DEBUG=server or PIIK_DEBUG=route On Unix, kill -USR1 <pid>; also exported at orderly shutdown

App Debug launch starts App collection immediately, including while waiting for a Site. Pages subsequently opened from the launcher also collect Browser logs; already-open Site pages use their own Debug control. It records Native capability results and subsequent capture, connection and local-server activity. Use --debug for failures before the launcher opens. This choice does not change the saved App configuration. When bypassing the mode selector, --debug and PIIK_DEBUG=client enable backend collection; enable the Browser control separately for browser-side diagnosis.

The Browser entry reloads the current page so collection includes connection startup. The opt-in follows App launch and room entry. Enabling it keeps the current URL parameters and any invitation fragment, but interrupts active sharing/viewing; enable it before reproducing the problem. Reports remain local until exported and shared by the user.

Server Debug is controlled by its startup environment or CLI, never by a remote page or room role. Browser ?debug=1 only enables that page's local collection; it does not enable App Native/capture or Server logging, or download their reports. The Server exposes no HTTP diagnostic export or pprof endpoint.

App/Server ZIP and Browser JSON reports are separate: when investigating Browser/App cooperation, include both from the same reproduction. Exporting either report does not stop an active share or upload anything. Browser export also remains available as await window.__PIIK_DEBUG__.export() in DevTools.

App logs go to logs beside the executable, falling back to Piik/logs in the OS user-cache directory when that default is unwritable. The TUI shows the actual path and the exported ZIP. --log-dir overrides PIIK_LOG_DIR; an explicit directory must be writable. Choosing a directory alone does not enable collection. Non-interactive Apps export at orderly shutdown; a returned App error also exports before the terminal closes. On App, PIIK_DEBUG=route alone retains console route tracing; use --debug for file collection and the D action.

Hosted logs use PIIK_LOG_DIR, otherwise systemd LOGS_DIRECTORY, otherwise logs under the working directory. The service unit supplies /var/log/piik with mode 0700. Normal service notices remain in the journal; detailed dependency records go into the report. Windows Server has no Unix signal trigger; forced process termination cannot create a final snapshot.

The report combines operation history and existing runtime evidence:

  • Native request IDs connect start/completion, duration, requested/applied profiles, source kind, codec/adapter selection and cancellation or failure. Async quality preparation retains that ID until its actual completion.
  • Capture process start/exit/EOF and streamed stderr include useful failure causes and system/HRESULT codes. Windows samples its existing WebRTC encoder observer during processing: input/output FPS, actual size, bitrate, encode time/usage, QP when available, drops, limitation flags and adaptation counts. Those are VSE counters, not a complete account of WGC mailbox overwrites.
  • Pion connection/ICE/DTLS and media-component diagnostics are included. Existing RTP/BWE/allocation observations, packet queue/drop counters, group demand/attachment changes and gateway/STUN outcomes explain delivery without adding a media-control loop or a new per-connection polling timer.
  • Browser records capture settings and sender readbacks, signaling and Native operations, meaningful error messages/stacks/causes and existing RTCStats. Pool observations distinguish native carrier reports, actual output and its assigned producer. Export adds Browser/platform metadata; diagnostic collection does not replace media APIs or control transport. Each RTC sample includes a compact ICE summary ahead of the bounded raw stats: reported pair states and selected-path type, prediction provenance, check responses and RTT when available. Pair counts describe that sample, not route attempts or a connection-success rate.

Each Go component keeps an 8 MiB current log and one 8 MiB backup. ZIPs contain these retained logs, a report marker, selected startup context, build/module and platform metadata, Go memory counters, sampled allocation profile (heap.pprof) and aggregate goroutine stacks. These are not raw process-memory or C++ memory dumps. A failed optional collector leaves useful files available; metadata.json lists included files, errors and partial status. ZIP write/disk failure still reports an export failure. Rotation and preexisting history are identified; retained logs do not claim a complete session history.

Exported ZIPs remain until the user moves or deletes them; rotation manages only the current logs. Repeated exports and Debug-mode error exits accumulate archives, so manage that directory's disk usage separately.

Browser retains up to 8,192 events and 8 MiB of compact event data in the current page. Reports identify retained sequence/time ranges, evicted/truncated events and collector failures. Field/record limits are explicit in the report. Browser reload/close loses that in-page history; export before closing it.

Credentials, authorization/cookies, invitation secrets, ICE passwords/fragments and private keys are filtered before persistence/export. Application media identities use diagnostic hashes where applicable; Browser/library technical identifiers, IP addresses, device information and file paths may remain. Do not treat a report as anonymous. Review it before sharing. Raw screen/audio payloads, arbitrary config/environment files and raw process-memory contents are not collected. Browser window titles and participant display names are omitted. Debug detail has CPU/I/O cost and should be enabled for investigation.

The research comparison records the mature project references and the reasons for this collection boundary.

Public And Private Ports

Port Scope Owner
TCP 80/443 public HTTP redirect and HTTPS/WSS reverse proxy
UDP 3478 public in-process STUN-only Piik listener
UDP 3479/3480 public when NAT prediction is enabled in-process auxiliary STUN-only Piik listeners
UDP 7882 (or SFU_UDP_PORT) public when SFU enabled in-process Piik WebRTC media
TCP 8787 private behind a proxy, or reachable within the chosen LAN for direct HTTPS Piik application

TCP 3478, TCP/TLS 5349, TURN relay ranges, media TCP, and other media ports remain closed. HTTPS/WSS transport is independent of the UDP-only media contract.

When NAT_PREDICTION_ENABLED=true, the server derives stun:<same-hostname>:3479 and :3480 from the first ordinary STUN authority on UDP 3478. Current pages use the advertised capability automatically unless the site requires SFU-only media. It adds no media route or third-party service. It needs both cloud security-group rules and the host firewall. Piik binds every required UDP listener before opening room persistence or accepting signaling; a bind failure rolls back all newly owned sockets. Close and End retire these listeners with the application. No other service may own the same listening ports. Opening a cloud port without a listener has no effect, and local binding alone does not prove external reachability. Disable the capability before removing firewall rules. Same-IP ports expose destination-port allocation behavior; a full RFC 5780 alternate-address test requires a second public IPv4.

Bounds

  • Site access uses constant-time secret comparison in the application. Reverse- proxy deployments also configure request rate limits there; direct HTTPS does not add a proxy rate limiter.
  • HTTP body, WebSocket payload, total/unauthed connections, room count, Viewer count, output buffers, endpoint copies, and SFU resources are bounded.
  • The four-digit code space fixes the maximum managed Host publications at 9,000; maximum subscription admission is that capacity times the configured per-room Viewer limit. These are admission bounds, not throughput claims.
  • One application process owns room authority and SFU admission. Multiple processes require a new shared atomic owner.