Free, open-source screen sharing for private live streams with friends. Watch together in a browser or self-host Piik. 免费开源的私密屏幕共享,支持游戏直播、一起看电影与自部署。
Public website
The static website source is site/. Its content and design follow the
public introduction guide.
Public Destinations
| Entry | Destination |
|---|---|
| Website | piik.tv |
| P2P-only demo on the separate US server | demo.piik.tv |
| App downloads and release notes | GitHub Releases |
| Download mirror for domestic access | AtomGit Releases |
| Documentation source | Reader guides, with a separate developer map |
GitHub Pages serves piik.tv behind
Cloudflare; both the GitHub origin and Cloudflare edge use HTTPS. Website and
Demo HTTP traffic use proxied DNS with origin cache headers respected.
The separate stun.piik.tv hostname stays DNS-only for direct UDP connectivity.
GitHub Pages hosts the website's static HTML, CSS and JavaScript. The Demo runs the Go room service, WebSocket signaling and UDP STUN on the separate US server.
Managed Hosting Assessment
Reviewed 2026-10-07. Keep the current deployment for this candidate. A managed container can reduce host administration, but must preserve public UDP, stable room authority and SQLite storage. Fly.io supports public UDP with a dedicated IPv4 address and a specific UDP bind address; external and internal UDP ports must match. Its dedicated IPv4 charge is $2/month before compute, storage and transfer. The assessment found no cost saving over the current server.
Cloudflare Containers disks are ephemeral by default. Keep live SQLite on persistent storage. A provider migration needs owner approval, a complete cost comparison, and storage, UDP and restart verification.
Public Demo Configuration
The chosen demo allows entry without a site password and provides P2P sharing without SFU fallback. Use the self-hosting runbook with:
PIIK_ENV=production
LISTEN_HOST=127.0.0.1
PORT=8787
PUBLIC_BASE_URL=https://demo.piik.tv
ALLOWED_ORIGINS=https://demo.piik.tv
SITE_ACCESS_PASSWORD=
ROOM_DATABASE_PATH=/var/lib/piik/rooms.sqlite
ROOM_EMPTY_TIMEOUT_SECONDS=3600
MAX_VIEWERS_PER_ROOM=20
STUN_URLS=stun:stun.piik.tv:3478
NAT_PREDICTION_ENABLED=true
SFU_UDP_PORT=
Point both hostnames at the US server: proxy demo.piik.tv through Cloudflare,
but leave stun.piik.tv DNS-only. Allow UDP 3478/3479/3480 directly to the server;
Cloudflare's ordinary HTTP proxy does not carry STUN. Caddy terminates origin
HTTPS/WSS. The demo uses the
standard systemd service, with its release
under /opt/piik/current and configuration at /etc/piik/piik.env. The service
unit provides the SQLite state directory. Room ownership, invitations and private-room
admission still apply. The configuration reference
owns each setting and its bounds.
The Demo's Caddy proxy compresses /assets/* with zstd/gzip. Successful
content-hashed JavaScript and CSS responses use
Cache-Control: public, max-age=31536000, immutable; other responses default to
no-store. Match both the hashed filename and a successful response status so
a missing bundle cannot acquire the long cache lifetime. Keep HTML, room APIs,
health responses and signaling outside static caching. New bundles have new
filenames; do not publish different bytes under an existing hashed URL.
Cloudflare caches those static bundles; HTML and API responses remain uncached,
and WebSocket signaling passes through to the room service. Media remains P2P.
For updates, follow the application release boundary and its artifact verification, health checks and recovery rules. Routine application rollback restores the previous executable while keeping current room data. This Caddy installation needs a scoped updater; the nginx-specific maintainer wrapper does not manage it.
Maintenance
Website HTML bypasses Cloudflare's edge cache and sends Cache-Control: no-cache
so Browsers revalidate it. Content-hashed scripts, styles and images keep their
ordinary cache policy. This keeps an older homepage from referring to assets
removed by a later Pages deployment. These rules match only the website hosts;
the Demo has its own cache owner above.
Copy the maintenance example to
.env.maintenance.local in the checkout and fill in local credentials and targets.
The file is ignored by Git. Use Node's built-in env-file option:
node --env-file=.env.maintenance.local scripts/release-maintenance.mjs website-check
node --env-file=.env.maintenance.local scripts/release-maintenance.mjs website-purge
node --env-file=.env.maintenance.local scripts/release-maintenance.mjs server-check
website-check reads the two rule phases, checks fresh HTML and compares
root/index asset references. website-purge clears those entry points from
Cloudflare; visitors' Browser caches remain separate. server-check is a read-only
SSH check of the Linux piik service, running package and public health.
Keep separate ignored env files or SSH aliases for different Server targets;
keep private connection details out of scripts. For package upload, cutover
and recovery, follow Server deployment.
Rule changes remain explicit infrastructure work: save the current rule phases and define their scoped rollback before modifying them. The maintenance commands do not rewrite rules or manage DNS. See Cloudflare's cache-rule order and response-header rules: edge eligibility and the Browser's cache header have separate owners.
Preview
With the repository's development dependencies installed:
npm ci --prefix site/docs
npm run build:website
npm run preview:website
Open http://127.0.0.1:18890. Rebuild after editing source. The homepage loads
film A when opened and unloads it when closed. Update its authored artwork when
product changes affect the scenes. The separate real-component fixture at
/film/ui/index.html supplies README screenshots.
Preview the built output, not site/index.html: the source is a template whose
shared theme controls and welcome text are filled in by the website build.
Publish the static build/site/ output. Vite preview supports HTTP byte ranges
for seeking the soundtrack. Keep asset links relative so both a custom
domain and GitHub's /Piik/ project path work. For a nested deployment, set
PIIK_DOCS_BASE=/Piik/docs/ when building; ordinary custom-domain builds use /docs/.
The public-film source owns the selected artwork and its runtime. The ordinary build includes only A's required runtime, fonts, audio and notices. Other candidates and the former 1.0 remain in Git history.
The homepage, film and demonstration frames use content-hashed script/style bundles; A's relative runtime tree also has one content-hashed directory. Their HTML references come from the same build, including imported dependencies; fixed filenames must not mix a new page with cached old controls or styles. Publish the complete output together.
Favicons share the App artwork and exports. The website build copies the public SVG/PNG/ICO assets for the homepage, film and documentation, keeping their URLs stable.
Google's favicon guidance
requires a crawlable homepage and icon, and supports one favicon per hostname.
Use the PNG/ICO links for search crawlers. Search engines control indexing and
display; repository pages on github.com use GitHub's favicon.
Documentation Build
site/docs/ configures VitePress; its isolated package and lockfile keep document
tooling out of the App/Server dependency tree. The pinned Vite override follows the
VitePress maintainer's guidance
to use the security-maintained Vite 6 line with stable VitePress 1. Remove the
override when a stable upstream release supplies a maintained version directly.
The explicit list in site/docs/pages.mjs maps original Markdown files to public
routes and sidebar labels. build.mjs stages only those files under ignored
build/docs-source/, then emits build/site/docs/ as part of build:website.
Edit the original Markdown, never a staged copy. Relative links between published
pages become local web links; references outside the list continue to GitHub.
Heading IDs reuse the repository checker's GitHub-style slug rule, so section
links work in both views without a second set of anchors.
The page edit link targets its original source. Developer context, TODO, research
and operational release records are not automatically published as reader pages.
The docs keep paired English/Chinese guides, shared site language preference, system/explicit appearance and the existing mascot. Search uses a local index and native word segmentation for Chinese and English, with no hosted search service. Technical configuration keeps its existing English owner on GitHub.
Both homepage and documentation are uploaded in the same Pages artifact. Do not run a second Pages deployment that would overwrite the homepage. Website/docs sources and the nested package remain outside product-release paths; shared product code and App/Server build inputs still follow the release boundary. Check links, language switching, search, keyboard/mobile use and the static HTML fallback when changing the public documentation.
Guide screenshots
With agent-browser installed, start npm run dev -- --host 127.0.0.1.
After changing pictured controls or copy, run in another terminal:
node scripts/update-guide-images.mjs http://127.0.0.1:8787
npm run build:website
The script regenerates the audio and network diagrams from shared icons and
palette, then captures /__tooltip-preview production components using sample data,
both languages, light/dark themes and reduced motion. It closes its own session.
Captures cover the mode selector, source picker, sharing settings, voice panel
and sample sharing-failure dialog. Place each beside the task it explains. Markdown uses GitHub's
#gh-light-mode-only / #gh-dark-mode-only image hints, which the documentation
theme also follows when its appearance control changes. Do not invert or tint
screenshots: capture the actual theme. SVG explanations inherit the page's
colour scheme and remain sharp at smaller sizes. scripts/update-guide-diagrams.tsx
generates the audio-path, network-path and virtual-LAN SVGs and embeds the shared palette in the three-step
illustration; build:website checks these generated parts for source freshness.
Adjust capture viewport/panel size to show complete choices and avoid unused space;
do not edit controls or labels inside the saved image.
AGENT_BROWSER_PATH overrides the CLI path. Inspect docs/assets/guide/ before
committing with UI/copy changes. Keep example captions; use no live-room data,
hand-edited text or duplicate mockups.
The build stages docs/assets/ and rewrites Markdown image paths to hashed URLs.
GitHub and the docs center share the sources; README links to the full tutorial.
To refresh the README's four room PNGs in the same run, pass an already-built website preview as the second URL:
node scripts/update-guide-images.mjs http://127.0.0.1:8787 http://127.0.0.1:18890
Build that preview from the current UI first. The README captures use the film's real-component fixture, with sample people and generated game artwork. The room illustration and quickstart SVG are authored explanations, not screenshots.
After changing pictured UI, refresh the affected PNGs with the capture command,
inspect them, then rebuild. build:website bundles components and guides and
checks generated hero artwork; check-docs.mjs validates image targets and
document links. Screenshot refresh and visual review are manual steps.
Downloads
The desktop row contains Windows, macOS and Linux; the mobile row contains Android and the iOS online entry. App downloads use fixed ZIP/APK filenames and each provider's native latest-attachment route:
- GitHub:
releases/latest/download/asset-name.zip(documentation). - AtomGit:
releases/download/latest/asset-name.zip(Windows download).
Both links follow provider publication without a website rebuild. Supported App architecture choices stay visible; one selection updates both providers' links. Both providers distribute the same universal Android APK for ARM64 and x64. The iOS entry opens the online version without promising an App release date. An optional GitHub metadata request supplies the latest version/date and its authored editorial title and one-line explanation; failure does not disable architecture selection. Without JavaScript, the default links remain Windows x64, Apple silicon, Linux x64 and Android universal. Publish a newly listed App package before deploying its website option. ARM64 Server packages alone do not enable an ARM64 App choice. Platform buttons say “Download from GitHub” / “GitHub 下载”; the secondary link says “Download from AtomGit” / “AtomGit 国内镜像下载”. Keep versions and archive formats out of these labels. Versioning owns package verification and completion of mirror publication. GitHub remains the primary source; the AtomGit download can temporarily lag while a mirror publication completes. Project, source-code and feedback links point to GitHub; AtomGit is only a download mirror. Verify the latest redirects and package checksums after releases.
Publish
- Verify the public copy and destinations above. Publish approved release artifacts before adding their download options to the website.
- In repository Settings > Pages, choose GitHub Actions as the source.
Use the dedicated Pages workflow, not publication of the repository root or
all of
docs/, which includes developer research and operational reference. - Set the approved
piik.tvcustom domain in Pages settings and configure its DNS using GitHub's current domain instructions. Actions publishing does not need aCNAMEfile in the source tree. - Accepted main pushes run CI first; success triggers Website, which checks
out that CI run's exact commit. Manual dispatch uses its selected
maincommit. Before publishing, both paths skip a build that is no longer current main; dispatch again for the latest commit when needed. The separate AtomGit mirror workflow does not gate Website deployment. Download links resolve through each provider, so publishing a package or retrying its mirror needs no link refresh. Onlybuild/site/is uploaded; website work does not package App/Server. Verify HTTPS, both languages, relative assets and per-platform download links.
Branch/PR pushes do not deploy. The workflow does not change DNS; the private production site and the US P2P-only demo remain separate deployments.
For rollback, dispatch the previously accepted site revision from a reviewed
revert on main; runtime App/Server binaries and databases are unaffected.