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