1# Plausible for paperclover.net
2
3[The service definition](../service/plausible/service.pkl) runs Plausible CE
43.2.1 with a private ClickHouse instance and a database allocated by the shared
5Postgres provider. The application and ClickHouse data live in the service's
6managed dataset. Previews start with fresh storage and separate secrets.
7
8The production address is `https://plausible.paperclover.net`. Bootstrap creates
9the owner from `config/site.pkl`, a private site for the base domain, and a
10tracker with outbound-link tracking. The reporting timezone matches the existing
11Cloud site. Bootstrap preserves existing passwords and site settings.
12
13## Sign in
14
15Open Plausible and sign in through Snowglobe. Accounts with `infra-admin` access
16receive separate browser sessions for the same Plausible owner account. The
17service's forward-auth sidecar has its own OIDC client and host-specific cookie;
18previews do not reuse production SSO credentials or cookies. Logout revokes the
19Plausible session, clears that app's SSO cookie, and returns to Snowglobe.
20
21The [session bridge](../service/plausible/sso.exs) wraps the existing Phoenix
22endpoint inside the official CE image. It checks forward auth before private
23HTTP requests and WebSocket handshakes, then uses Plausible's normal session API.
24Only tracker JavaScript, event ingestion, and health checks bypass sign-in.
25Tracking continues if SSO fails; private routes fail closed. Existing WebSockets
26follow the usual forward-auth behavior: access is checked when they connect.
27
28Native password prompts for sensitive account settings use the owner password.
29The `initial_admin_password` secret in Snowglobe's service **Secrets** tab is an
30initial credential, not a password-reset control. Password changes do not affect
31SSO. The app cannot change the configured owner email or delete this shared
32account; those operations require coordinated server administration.
33
34Email is disabled at Clover's request. Password-reset messages, invitations, and
35scheduled reports are captured locally rather than delivered.
36
37When upgrading CE, rerun [the bridge checks](../service/plausible/sso-test.exs)
38and the browser login/logout checks: the bridge uses CE's session APIs. Run the
39script in a disposable preview container, using stdin with
40`/app/bin/plausible eval 'Code.eval_string(IO.read(:stdio, :eof))'`. It starts a
41separate BEAM with a loopback-only mock SSO server, creates temporary owner
42sessions, and removes them afterward. It does not replace the running preview's
43SSO configuration.
44
45## Cloud import and tracking cutover
46
47The [supported migration](https://plausible.io/docs/csv-import) uses a full export
48from Cloud's **Site settings → Imports & exports → Prepare download**. A dashboard
49report ZIP is a different export and cannot substitute for it.
50
511. Deploy the described, conflict-free `main` with `python3 tools/deploy.py prod`
52 after production is requested. Preview data is disposable and is not promoted.
532. Sign in to production and open **paperclover.net → Settings → General →
54 Review installation**. Copy its complete native snippet. Its script ID belongs
55 to the self-hosted installation; the existing Cloud script ID cannot be reused.
563. Plan the website switch at midnight in the site's reporting timezone. Imports
57 end before the first native tracking date, so a switch during a reporting day
58 would exclude that day's earlier Cloud visits from the combined dashboard.
59 Keep Cloud tracking active until the switch, then replace its loader and init
60 block with the self-hosted snippet. Keep existing `plausible(...)` event calls.
614. Export Cloud again after its final reporting day completes. Preserve the
62 complete ZIP in the restricted import store, outside preview storage. The
63 rehearsal export is an earlier snapshot, not a final cutover export.
645. Unzip the export and select the ten supported CSVs together in the destination's
65 **Settings → Imports & exports → Import from CSV**. Wait for the completed
66 import, then compare its dates and metrics with the export. Replace an earlier
67 Cloud import instead of adding overlapping snapshots. Preserve matching
68 custom goals from Cloud's Goals settings; CSV import does not recreate them.
696. Verify pageviews and outbound clicks through the real website, then check the
70 dashboard. Keep the Cloud account and export until the history and cutover have
71 been checked. Remove the temporary preview through the deployment tool when
72 review is finished.
73
74CE 3.2.1 does not import `imported_custom_props_*.csv`. Preserve that file in the
75original ZIP: arbitrary historical custom-property breakdowns cannot be viewed
76in CE. Imported reports are aggregates with fewer filter combinations than
77native events. Cloud exports also exclude earlier third-party imports.
78
79## Rehearsal evidence
80
81On 2026-10-19 UTC, release `12a2725e1a1372ce` passed on Snow Globe at
82`https://plausible-preview-3234cb91.paperclover.net`. Owner login, disabled
83registration, private dashboards, the CSV upload, keyboard filters, mobile,
84both themes, and installation instructions were checked in a real browser.
85
86All supported metrics matched the source across ten imported tables before and
87after reallocation. A separate disposable site accepted and persisted browser
88pageviews and outbound clicks, then was removed. The real site's native event
89table stayed empty, preserving the full import interval. Both application tasks
90were healthy with zero restarts after the final reallocation; the Nomad job
91validated. ClickHouse rejected anonymous queries.
92
93The original Cloud ZIP and detailed comparison report are owner-readable under
94`/var/lib/snowglobe/imports/plausible/`, outside the preview dataset. No live
95website tracker or production release was changed.
96
97The SSO rehearsal used release `aa77dda7f64c3c86` at the same preview address.
98The auth sidecar, application, and ClickHouse were healthy with zero restarts;
99the deployed Nomad job validated. An authenticated browser reached the shared
100owner's sites, historical reports, and settings without a Plausible password,
101and its native LiveView WebSocket connected.
102
103The bridge checks passed signed-session creation/reuse, exact admin roles,
104forged-header rejection, native-cookie-only rejection, session expiry, logout,
105CSRF, encoded paths, auth failure, and fresh-site bootstrap. An anonymous browser
106loaded the generated tracker and persisted a pageview and outbound click in a
107disposable site. That site was removed afterward. All ten imported tables still
108matched the Cloud export, and the real site's native events remained empty.
109Detailed checks and tracking evidence remain in the restricted import store.
110
111The initial rehearsal used the installed Snowglobe staging manager and OIDC
112provisioner against sources from an older working change. Production uses current
113`main`'s service schema and deployment tooling.