diff --git a/service/plausible/bootstrap.exs b/service/plausible/bootstrap.exs new file mode 100644 index 0000000000000000000000000000000000000000..234d8de3ba42d92de618a3a9b6df4dad72d1b122 --- /dev/null +++ b/service/plausible/bootstrap.exs @@ -0,0 +1,54 @@ +alias Plausible.{Auth.User, Repo, Sites} + +# Provision the first owner before the public registration page can be served. +endpoint = Application.fetch_env!(:plausible, PlausibleWeb.Endpoint) +Application.put_env(:plausible, PlausibleWeb.Endpoint, Keyword.put(endpoint, :server, false)) +oban = Application.fetch_env!(:plausible, Oban) +Application.put_env(:plausible, Oban, Keyword.merge(oban, queues: [], plugins: [], peer: false)) +{:ok, _} = Application.ensure_all_started(:plausible) + +{:ok, _} = + Repo.transaction(fn -> + email = System.fetch_env!("ADMIN_EMAIL") + + user = + Repo.get_by(User, email: email) || + if Repo.exists?(User) do + raise "Owner email does not match the existing installation" + else + password = System.fetch_env!("INITIAL_ADMIN_PASSWORD") + + case Repo.insert( + User.new(%{ + email: email, + name: "Clover", + password: password, + password_confirmation: password + }) + ) do + {:ok, user} -> user + {:error, _} -> raise "Could not create the Plausible owner" + end + end + + domain = System.fetch_env!("SITE_DOMAIN") + + site = + if site = Sites.get_by_domain(domain) do + unless Sites.get_for_user(user, domain, roles: [:owner]) do + raise "The configured owner does not own this site" + end + + site + else + {:ok, %{site: site}} = + Sites.create(user, %{domain: domain, timezone: System.fetch_env!("SITE_TIMEZONE")}) + + site + end + + PlausibleWeb.Tracker.get_or_create_tracker_script_configuration!(site, %{ + installation_type: :manual, + outbound_links: true + }) + end) diff --git a/service/plausible/clickhouse-users.xml b/service/plausible/clickhouse-users.xml new file mode 100644 index 0000000000000000000000000000000000000000..b5d1089cc54db529e22fada403e09b5243ed0551 --- /dev/null +++ b/service/plausible/clickhouse-users.xml @@ -0,0 +1,20 @@ + + + + + + ::/0 + default + default + + + + + 1 + 8192 + 1 + 0 + 0 + + + diff --git a/service/plausible/clickhouse.xml b/service/plausible/clickhouse.xml new file mode 100644 index 0000000000000000000000000000000000000000..3ea946af23427791ef591a58e4df8b951efd6164 --- /dev/null +++ b/service/plausible/clickhouse.xml @@ -0,0 +1,24 @@ + + 0.0.0.0 + + warning + true + + + + 134217728 + 3221225472 + 8 + 4 + 4 + 4 + + + + + + + + + + diff --git a/service/plausible/service.pkl b/service/plausible/service.pkl new file mode 100644 index 0000000000000000000000000000000000000000..8e129881abbac147d45af6c6e8b5be01fcba250c --- /dev/null +++ b/service/plausible/service.pkl @@ -0,0 +1,115 @@ +amends "../../config/Service.pkl" + +import "../../config/site.pkl" as site +import "../../config/OpenID.pkl" as sso +import "../forward-auth/service.pkl" as forwardAuth +import "../postgres/service.pkl" as postgres + +name = "Plausible" +tagline = "Website analytics" +access = "infra-admin" +stageIsolation = "fresh" +healthyDeadline = "10m" + +requirements { + new postgres.Database { name = "plausible" } + new sso.Client { + clientId = module.id + name = module.name + redirectUris { "https://\(module.containers["app"].http.hostname)/snow.oauth2/callback" } + } +} + +secrets { + ["secret_key_base"] { bytes = 64 } + ["clickhouse_password"] {} + ["initial_admin_password"] {} + ["cookie"] = forwardAuth.secrets["cookie"] +} + +containers { + ["auth"] = (forwardAuth.container!!) { + lifecycle = "prestartSidecar" + http = null + tcp { + new { name = "oauth"; containerPort = 4180; loopback = false } + } + env { + ["OAUTH2_PROXY_COOKIE_NAME"] = "_snow_\(module.id)" + ["OAUTH2_PROXY_COOKIE_DOMAINS"] = module.containers["app"].http.hostname!! + ["OAUTH2_PROXY_WHITELIST_DOMAINS"] = "\(module.containers["app"].http.hostname),\(sso.hostname)" + ["OAUTH2_PROXY_REDIRECT_URL"] = "https://\(module.containers["app"].http.hostname)/snow.oauth2/callback" + ["OAUTH2_PROXY_AUTH_LOGGING"] = "false" + ["OAUTH2_PROXY_REQUEST_LOGGING"] = "false" + } + } + + ["clickhouse"] { + image = "docker.io/clickhouse/clickhouse-server@sha256:cd450891db46cc6ffe313ca2b0fb7dbfb897a6873ca74a724cbe050a2cf62621" + lifecycle = "prestartSidecar" + cpu = 400 + memory = 4096 + tcp { + new { + name = "db" + containerPort = 8123 + loopback = false + } + } + volumes { + ["/var/lib/clickhouse"] {} + ["/etc/clickhouse-server/config.d/studio.xml"] { config = "clickhouse.xml" } + ["/etc/clickhouse-server/users.d/studio.xml"] { config = "clickhouse-users.xml" } + } + env { + ["CLICKHOUSE_SKIP_USER_SETUP"] = "1" + ["PLAUSIBLE_CLICKHOUSE_PASSWORD"] = "${secret.own.clickhouse_password}" + } + } + + ["app"] { + image = "ghcr.io/plausible/community-edition@sha256:33e60bfb40f2df5da00f8753b76fad04f67dba3abe6d73eb516e440e3fb62985" + entrypoint = "/bin/sh" + args { + "-ec" + """ + timeout 90 /bin/sh -c 'until /entrypoint.sh db createdb; do sleep 2; done' + /entrypoint.sh db migrate + /app/bin/plausible eval 'Code.eval_file("/bootstrap.exs")' + exec /app/bin/plausible eval 'Code.eval_file("/sso.exs")' + """ + } + cpu = 500 + memory = 2048 + http { + containerPort = 8000 + subdomain = "plausible" + checkPath = "/api/health" + forwardRealIp = true + } + volumes { + ["/var/lib/plausible"] {} + ["/bootstrap.exs"] { config = "bootstrap.exs" } + ["/sso.exs"] { config = "sso.exs" } + } + env { + ["BASE_URL"] = "https://\(module.containers["app"].http.hostname)" + ["SECRET_KEY_BASE"] = "${secret.own.secret_key_base}" + ["ADMIN_EMAIL"] = site.ownerEmail + ["INITIAL_ADMIN_PASSWORD"] = "${secret.own.initial_admin_password}" + ["SITE_DOMAIN"] = site.domain + ["SITE_TIMEZONE"] = "America/Detroit" + ["SSO_HOME_URL"] = "\(sso.issuer)/" + ["DISABLE_REGISTRATION"] = "true" + ["ENABLE_EMAIL_VERIFICATION"] = "false" + ["MAILER_ADAPTER"] = "Bamboo.LocalAdapter" + ["TMPDIR"] = "/var/lib/plausible/tmp" + ["ERL_FLAGS"] = "+S 4:4" + } + envTemplate = """ + {{ with $db := nomadVar "nomad/jobs/\(module.id)/inputs/database" }}{{ range nomadService 1 (env "NOMAD_ALLOC_ID") "postgres" }}DATABASE_URL=postgres://{{ index $db "username" }}:{{ index $db "password" }}@\(module.nomadHostPort)/{{ index $db "name" }}{{ end }}{{ end }} + {{ with $own := nomadVar "nomad/jobs/\(module.id)" }}{{ range nomadService 1 (env "NOMAD_ALLOC_ID") "\(module.id)-clickhouse" }}CLICKHOUSE_DATABASE_URL=http://plausible:{{ index $own "clickhouse_password" }}@\(module.nomadHostPort)/plausible_events_db{{ end }}{{ end }} + {{ range nomadService 1 (env "NOMAD_ALLOC_ID") "\(module.id)-auth" }}SSO_AUTH_URL=http://\(module.nomadHostPort){{ end }} + """ + } +} diff --git a/service/plausible/sso-test.exs b/service/plausible/sso-test.exs new file mode 100644 index 0000000000000000000000000000000000000000..6c601ec1d3366f9d3989a331bfd1ae086fc27c1b --- /dev/null +++ b/service/plausible/sso-test.exs @@ -0,0 +1,251 @@ +endpoint = Application.fetch_env!(:plausible, PlausibleWeb.Endpoint) +Application.put_env(:plausible, PlausibleWeb.Endpoint, Keyword.put(endpoint, :server, false)) +oban = Application.fetch_env!(:plausible, Oban) +Application.put_env(:plausible, Oban, Keyword.merge(oban, queues: [], plugins: [], peer: false)) +{:ok, _} = Application.ensure_all_started(:plausible) +{:__block__, _, [bridge | _]} = Code.string_to_quoted!(File.read!("/sso.exs")) +Code.eval_quoted(bridge) + +defmodule Snowglobe.PlausibleAuthFixture do + import Plug.Conn + def init(opts), do: opts + + def call(conn, _opts) do + conn = fetch_cookies(conn) + + case {conn.request_path, conn.req_cookies["fixture"]} do + {_, "down"} -> + send_resp(conn, 503, "Unavailable") + + {"/ping", _} -> + send_resp(conn, 200, "OK") + + {"/snow.oauth2/auth", "admin"} -> + conn + |> put_resp_header("x-auth-request-groups", "role:media,role:infra-admin") + |> send_resp(204, "") + + {"/snow.oauth2/auth", "similar-role"} -> + conn + |> put_resp_header("x-auth-request-groups", "role:infra-admin-extra") + |> send_resp(204, "") + + {"/snow.oauth2/auth", _} -> + send_resp(conn, 401, "Unauthorized") + + _ -> + conn + |> prepend_resp_headers([ + {"set-cookie", "one=; Max-Age=0"}, + {"set-cookie", "two=; Max-Age=0"} + ]) + |> put_resp_header("location", System.fetch_env!("SSO_HOME_URL")) + |> send_resp(302, "") + end + end +end + +{:ok, _} = Plug.Cowboy.http(Snowglobe.PlausibleAuthFixture, [], ip: {127, 0, 0, 1}, port: 0) +port = :ranch.get_port(Snowglobe.PlausibleAuthFixture.HTTP) +System.put_env("SSO_AUTH_URL", "http://127.0.0.1:#{port}") + +import Plug.Conn +alias PlausibleWeb.{Endpoint, UserAuth} + +request = fn method, path, cookie, headers -> + conn = + Plug.Test.conn(method, System.fetch_env!("BASE_URL") <> path) + |> put_req_header("cookie", cookie) + + conn = + Enum.reduce(headers, conn, fn {name, value}, conn -> put_req_header(conn, name, value) end) + + Snowglobe.Plausible.call(conn, []) +end + +check = fn condition, name -> + unless condition, do: raise("Failed: " <> name) + IO.puts("PASS " <> name) +end + +owner_cookie = fn -> + conn = request.(:get, "/sites", "fixture=admin", []) + value = conn.resp_cookies["_plausible_key"].value + config = Plug.Session.init(Endpoint.runtime_session_opts()) + + {_, session} = + Plug.Session.COOKIE.get( + %{conn | secret_key_base: Endpoint.config(:secret_key_base)}, + value, + config.store_config + ) + + token = Map.fetch!(session, "user_token") + Process.put(:created_tokens, [token | Process.get(:created_tokens, [])]) + {"_plausible_key=" <> value, token, conn} +end + +try do + conn = + request.(:get, "/sites?period=all", "", [ + {"x-auth-request-groups", "role:infra-admin"}, + {"authorization", "Basic ZmFrZTpmYWtl"} + ]) + + destination = + "/snow.oauth2/start?" <> + URI.encode_query(%{"rd" => System.fetch_env!("BASE_URL") <> "/sites?period=all"}) + + check.( + conn.status == 302 and get_resp_header(conn, "location") == [destination] and + not Map.has_key?(conn.resp_cookies, "_plausible_key"), + "forged headers cannot bypass SSO" + ) + + conn = request.(:get, "/sites", "fixture=similar-role", []) + + check.( + conn.status == 403 and not Map.has_key?(conn.resp_cookies, "_plausible_key"), + "exact role match" + ) + + {cookie, token, login} = owner_cookie.() + + owner = + case Plausible.Auth.UserSessions.get_by_token(token) do + {:ok, %{user: user}} -> user.email == System.fetch_env!("ADMIN_EMAIL") + _ -> false + end + + secure_cookie = + Enum.any?(get_resp_header(login, "set-cookie"), fn value -> + String.starts_with?(value, "_plausible_key=") and + Enum.all?( + ["secure", "httponly", "samesite=lax"], + &String.contains?(String.downcase(value), &1) + ) + end) + + check.(owner and secure_cookie, "secure normal owner session") + + conn = request.(:get, "/sites", "fixture=admin; " <> cookie, []) + + check.( + conn.status == 200 and not Map.has_key?(conn.resp_cookies, "logged_in"), + "reuse the existing owner session" + ) + + conn = request.(:get, "/sites", cookie, []) + check.(conn.status == 302, "Plausible cookie alone cannot enter the dashboard") + conn = request.(:get, "/api/stats/paperclover.net/top-stats", cookie, []) + check.(conn.status == 401, "Plausible cookie alone cannot read statistics") + + Plausible.Auth.UserSessions.remove_by_token(token) + conn = request.(:get, "/sites?period=all", "fixture=admin; " <> cookie, []) + value = conn.resp_cookies["_plausible_key"].value + config = Plug.Session.init(Endpoint.runtime_session_opts()) + + {_, session} = + Plug.Session.COOKIE.get( + %{conn | secret_key_base: Endpoint.config(:secret_key_base)}, + value, + config.store_config + ) + + Process.put(:created_tokens, [session["user_token"] | Process.get(:created_tokens, [])]) + valid = match?({:ok, _}, UserAuth.get_user_session(session)) + + check.( + conn.status == 302 and get_resp_header(conn, "location") == ["/sites?period=all"] and valid, + "replace expired sessions and preserve the destination" + ) + + {cookie, token, _} = owner_cookie.() + conn = request.(:get, "/logout", "fixture=admin; " <> cookie, []) + revoked = match?({:error, :not_found}, Plausible.Auth.UserSessions.get_by_token(token)) + + destination = + "/snow.oauth2/sign_out?" <> URI.encode_query(%{"rd" => System.fetch_env!("SSO_HOME_URL")}) + + check.( + conn.status == 302 and get_resp_header(conn, "location") == [destination] and revoked, + "logout revokes the owner session" + ) + + conn = request.(:get, "/snow.oauth2/sign_out", "", []) + check.(length(get_resp_header(conn, "set-cookie")) == 2, "forward every SSO logout cookie") + + for {method, path, cookie} <- [ + {:post, "/settings/security/password", ""}, + {:get, "/live/websocket", ""}, + {:post, "/settings/security/password", "fixture=admin"}, + {:get, "/live/websocket", "fixture=admin"} + ] do + conn = request.(method, path, cookie, []) + + check.( + conn.status == 401 and not Map.has_key?(conn.resp_cookies, "_plausible_key"), + "private writes and WebSockets require both sessions" + ) + end + + {cookie, _, _} = owner_cookie.() + + rejected = + try do + request.(:post, "/settings/security/password", "fixture=admin; " <> cookie, []).status == + 403 + rescue + e -> + is_struct(e, Plug.CSRFProtection.InvalidCSRFTokenError) or + (is_struct(e, Plug.Conn.WrapperError) and + is_struct(e.reason, Plug.CSRFProtection.InvalidCSRFTokenError)) + end + + check.(rejected, "native CSRF protection remains active") + + for path <- ["/settings/security/email", "/settings/security/%65mail", "/me"] do + conn = request.(:post, path, "fixture=admin; " <> cookie, []) + check.(conn.status == 403, "the configured owner identity cannot be changed through the app") + end + + conn = request.(:get, "/sites", "fixture=down", []) + check.(conn.status == 503, "SSO failure closes private pages") + conn = request.(:get, "/api/health", "fixture=down", []) + check.(conn.status == 503, "health includes the auth sidecar") + conn = request.(:get, "/js/script.js", "fixture=down", []) + check.(conn.status == 200, "scripts remain public during SSO failure") + + conn = + request.(:options, "/api/event", "", [ + {"origin", "https://paperclover.net"}, + {"access-control-request-method", "POST"} + ]) + + check.(conn.status in [200, 204], "tracking preflight remains public") + + for path <- ["/js/../sites", "/js/%2e%2e/sites", "/js/%2f..%2fsites", "/api/event/../stats"] do + conn = request.(:get, path, cookie, []) + + check.( + conn.status in [302, 401] and not Map.has_key?(conn.resp_cookies, "_plausible_key"), + "public paths cannot traverse into private pages" + ) + end + + original_domain = System.fetch_env!("SITE_DOMAIN") + fixture_domain = "plausible-sso-bootstrap.invalid" + System.put_env("SITE_DOMAIN", fixture_domain) + + try do + Code.eval_file("/bootstrap.exs") + check.(Plausible.Sites.get_by_domain(fixture_domain) != nil, "fresh site bootstrap") + after + System.put_env("SITE_DOMAIN", original_domain) + if site = Plausible.Sites.get_by_domain(fixture_domain), do: Plausible.Site.Removal.run(site) + end + + IO.puts("SSO boundary checks passed") +after + Enum.each(Process.get(:created_tokens, []), &Plausible.Auth.UserSessions.remove_by_token/1) +end diff --git a/service/plausible/sso.exs b/service/plausible/sso.exs new file mode 100644 index 0000000000000000000000000000000000000000..a340fc4e67707044efeb725dba6683ba34d336ff --- /dev/null +++ b/service/plausible/sso.exs @@ -0,0 +1,176 @@ +defmodule Snowglobe.Plausible do + import Plug.Conn + alias PlausibleWeb.{Endpoint, UserAuth} + + @unavailable "Sign-in is unavailable. Try again." + @sign_in "Open Plausible to sign in, then try again." + + def init(opts), do: opts + + def call(conn, _opts) do + public = + (conn.method in ["GET", "HEAD"] and + Regex.match?(~r{\A/js/[A-Za-z0-9._-]+\.js\z}, conn.request_path)) or + (conn.method in ["POST", "OPTIONS"] and conn.request_path == "/api/event") + + cond do + conn.method in ["GET", "HEAD"] and conn.request_path == "/api/health" -> + case auth_request(conn, "/ping") do + {:ok, %{status: 200}} -> Endpoint.call(conn, Endpoint.init([])) + _ -> send_resp(conn, 503, @unavailable) + end + + public -> + Endpoint.call(conn, Endpoint.init([])) + + conn.method == "GET" and + conn.request_path in ~w(/snow.oauth2/start /snow.oauth2/callback /snow.oauth2/sign_in /snow.oauth2/sign_out) -> + case auth_request(conn, conn.request_path <> query(conn)) do + {:ok, response} -> + conn + |> prepend_resp_headers( + Enum.reject(response.headers, fn {name, _} -> + name in ~w(connection content-length transfer-encoding) + end) + ) + |> send_resp(response.status, response.body) + + {:error, _} -> + send_resp(conn, 503, @unavailable) + end + + true -> + authenticate(conn) + end + end + + defp authenticate(conn) do + case auth_request(conn, "/snow.oauth2/auth") do + {:ok, %{status: status, headers: headers}} when status in 200..299 -> + groups = + for {"x-auth-request-groups", value} <- headers, + group <- String.split(value, ~r/[,\s]+/, trim: true), + do: group + + conn = + prepend_resp_headers( + conn, + Enum.filter(headers, fn {name, _} -> name == "set-cookie" end) + ) + + if "role:infra-admin" in groups do + owner_session(conn) + else + send_resp( + conn, + 403, + "Your account cannot access Plausible. Ask an administrator for access." + ) + end + + {:ok, %{status: status}} when status in [401, 403] -> + if conn.method in ["GET", "HEAD"] and + not String.starts_with?(conn.request_path, ["/api/", "/live/"]) do + destination = System.fetch_env!("BASE_URL") <> conn.request_path <> query(conn) + + Phoenix.Controller.redirect(conn, + to: "/snow.oauth2/start?" <> URI.encode_query(%{"rd" => destination}) + ) + else + send_resp(conn, 401, @sign_in) + end + + _ -> + send_resp(conn, 503, @unavailable) + end + end + + defp owner_session(conn) do + conn = %{conn | secret_key_base: Endpoint.config(:secret_key_base)} |> fetch_cookies() + config = Plug.Session.init(Endpoint.runtime_session_opts()) + + # Leave the endpoint responsible for installing its session hook. + session = + if cookie = conn.req_cookies[config.key] do + {_, session} = Plug.Session.COOKIE.get(conn, cookie, config.store_config) + UserAuth.get_user_session(session) + end + + owner_email = System.fetch_env!("ADMIN_EMAIL") + + cond do + conn.method in ["POST", "DELETE"] and + Enum.map(conn.path_info, &URI.decode/1) in [["settings", "security", "email"], ["me"]] -> + send_resp( + conn, + 403, + "This shared owner account uses the configured email address. Ask the server administrator to change or remove it." + ) + + conn.method == "GET" and conn.request_path == "/logout" -> + conn = conn |> Plug.Session.call(config) |> fetch_session() |> UserAuth.log_out_user() + + Phoenix.Controller.redirect(conn, + to: + "/snow.oauth2/sign_out?" <> + URI.encode_query(%{"rd" => System.fetch_env!("SSO_HOME_URL")}) + ) + + conn.method == "GET" and conn.request_path == "/login" -> + Phoenix.Controller.redirect(conn, to: "/sites") + + match?({:ok, %{user: %{email: ^owner_email}}}, session) -> + {:ok, user_session} = session + Endpoint.call(assign(conn, :current_user_session, user_session), Endpoint.init([])) + + conn.method == "GET" and not String.starts_with?(conn.request_path, ["/api/", "/live/"]) -> + user = Plausible.Repo.get_by!(Plausible.Auth.User, email: owner_email) + + conn + |> put_private(:phoenix_endpoint, Endpoint) + |> Plug.Session.call(config) + |> fetch_session() + |> put_resp_header("cache-control", "no-store") + |> UserAuth.log_in_user(user, conn.request_path <> query(conn)) + + true -> + send_resp(conn, 401, @sign_in) + end + end + + defp query(%{query_string: ""}), do: "" + defp query(conn), do: "?" <> conn.query_string + + defp auth_request(conn, path) do + host = URI.parse(System.fetch_env!("BASE_URL")).host + + headers = + Enum.filter(conn.req_headers, fn {name, _} -> name in ~w(cookie user-agent accept) end) ++ + [ + {"x-forwarded-proto", "https"}, + {"x-forwarded-host", host}, + {"x-forwarded-uri", conn.request_path <> query(conn)}, + {"x-forwarded-method", conn.method} + ] + + Finch.build(:get, System.fetch_env!("SSO_AUTH_URL") <> path, headers) + |> Finch.request(Plausible.Finch, pool_timeout: 1_000, receive_timeout: 3_000) + end +end + +# Keep a single listener so no route can bypass forward authentication. +endpoint = Application.fetch_env!(:plausible, PlausibleWeb.Endpoint) +Application.put_env(:plausible, PlausibleWeb.Endpoint, Keyword.put(endpoint, :server, false)) +Application.put_env(:plug_cowboy, :conn_in_exception_metadata, false) +{:ok, _} = Application.ensure_all_started(:plausible) + +{:ok, _} = + Supervisor.start_child( + Plausible.Supervisor, + {Plug.Cowboy, + scheme: :http, + plug: Snowglobe.Plausible, + options: [port: Application.fetch_env!(:plausible, PlausibleWeb.Endpoint)[:http][:port]]} + ) + +Process.sleep(:infinity) diff --git a/tools/plausible.md b/tools/plausible.md new file mode 100644 index 0000000000000000000000000000000000000000..0dd8ac1e6b0b52ac3b9165ba8f8acff2a62293d0 --- /dev/null +++ b/tools/plausible.md @@ -0,0 +1,113 @@ +# Plausible for paperclover.net + +[The service definition](../service/plausible/service.pkl) runs Plausible CE +3.2.1 with a private ClickHouse instance and a database allocated by the shared +Postgres provider. The application and ClickHouse data live in the service's +managed dataset. Previews start with fresh storage and separate secrets. + +The production address is `https://plausible.paperclover.net`. Bootstrap creates +the owner from `config/site.pkl`, a private site for the base domain, and a +tracker with outbound-link tracking. The reporting timezone matches the existing +Cloud site. Bootstrap preserves existing passwords and site settings. + +## Sign in + +Open Plausible and sign in through Snowglobe. Accounts with `infra-admin` access +receive separate browser sessions for the same Plausible owner account. The +service's forward-auth sidecar has its own OIDC client and host-specific cookie; +previews do not reuse production SSO credentials or cookies. Logout revokes the +Plausible session, clears that app's SSO cookie, and returns to Snowglobe. + +The [session bridge](../service/plausible/sso.exs) wraps the existing Phoenix +endpoint inside the official CE image. It checks forward auth before private +HTTP requests and WebSocket handshakes, then uses Plausible's normal session API. +Only tracker JavaScript, event ingestion, and health checks bypass sign-in. +Tracking continues if SSO fails; private routes fail closed. Existing WebSockets +follow the usual forward-auth behavior: access is checked when they connect. + +Native password prompts for sensitive account settings use the owner password. +The `initial_admin_password` secret in Snowglobe's service **Secrets** tab is an +initial credential, not a password-reset control. Password changes do not affect +SSO. The app cannot change the configured owner email or delete this shared +account; those operations require coordinated server administration. + +Email is disabled at Clover's request. Password-reset messages, invitations, and +scheduled reports are captured locally rather than delivered. + +When upgrading CE, rerun [the bridge checks](../service/plausible/sso-test.exs) +and the browser login/logout checks: the bridge uses CE's session APIs. Run the +script in a disposable preview container, using stdin with +`/app/bin/plausible eval 'Code.eval_string(IO.read(:stdio, :eof))'`. It starts a +separate BEAM with a loopback-only mock SSO server, creates temporary owner +sessions, and removes them afterward. It does not replace the running preview's +SSO configuration. + +## Cloud import and tracking cutover + +The [supported migration](https://plausible.io/docs/csv-import) uses a full export +from Cloud's **Site settings → Imports & exports → Prepare download**. A dashboard +report ZIP is a different export and cannot substitute for it. + +1. Deploy the described, conflict-free `main` with `python3 tools/deploy.py prod` + after production is requested. Preview data is disposable and is not promoted. +2. Sign in to production and open **paperclover.net → Settings → General → + Review installation**. Copy its complete native snippet. Its script ID belongs + to the self-hosted installation; the existing Cloud script ID cannot be reused. +3. Plan the website switch at midnight in the site's reporting timezone. Imports + end before the first native tracking date, so a switch during a reporting day + would exclude that day's earlier Cloud visits from the combined dashboard. + Keep Cloud tracking active until the switch, then replace its loader and init + block with the self-hosted snippet. Keep existing `plausible(...)` event calls. +4. Export Cloud again after its final reporting day completes. Preserve the + complete ZIP in the restricted import store, outside preview storage. The + rehearsal export is an earlier snapshot, not a final cutover export. +5. Unzip the export and select the ten supported CSVs together in the destination's + **Settings → Imports & exports → Import from CSV**. Wait for the completed + import, then compare its dates and metrics with the export. Replace an earlier + Cloud import instead of adding overlapping snapshots. Preserve matching + custom goals from Cloud's Goals settings; CSV import does not recreate them. +6. Verify pageviews and outbound clicks through the real website, then check the + dashboard. Keep the Cloud account and export until the history and cutover have + been checked. Remove the temporary preview through the deployment tool when + review is finished. + +CE 3.2.1 does not import `imported_custom_props_*.csv`. Preserve that file in the +original ZIP: arbitrary historical custom-property breakdowns cannot be viewed +in CE. Imported reports are aggregates with fewer filter combinations than +native events. Cloud exports also exclude earlier third-party imports. + +## Rehearsal evidence + +On 2026-10-19 UTC, release `12a2725e1a1372ce` passed on Zenith at +`https://plausible-preview-3234cb91.paperclover.net`. Owner login, disabled +registration, private dashboards, the CSV upload, keyboard filters, mobile, +both themes, and installation instructions were checked in a real browser. + +All supported metrics matched the source across ten imported tables before and +after reallocation. A separate disposable site accepted and persisted browser +pageviews and outbound clicks, then was removed. The real site's native event +table stayed empty, preserving the full import interval. Both application tasks +were healthy with zero restarts after the final reallocation; the Nomad job +validated. ClickHouse rejected anonymous queries. + +The original Cloud ZIP and detailed comparison report are owner-readable under +`/var/lib/snowglobe/imports/plausible/`, outside the preview dataset. No live +website tracker or production release was changed. + +The SSO rehearsal used release `aa77dda7f64c3c86` at the same preview address. +The auth sidecar, application, and ClickHouse were healthy with zero restarts; +the deployed Nomad job validated. An authenticated browser reached the shared +owner's sites, historical reports, and settings without a Plausible password, +and its native LiveView WebSocket connected. + +The bridge checks passed signed-session creation/reuse, exact admin roles, +forged-header rejection, native-cookie-only rejection, session expiry, logout, +CSRF, encoded paths, auth failure, and fresh-site bootstrap. An anonymous browser +loaded the generated tracker and persisted a pageview and outbound click in a +disposable site. That site was removed afterward. All ten imported tables still +matched the Cloud export, and the real site's native events remained empty. +Detailed checks and tracking evidence remain in the restricted import store. + +The initial rehearsal used the installed Snowglobe staging manager and OIDC +provisioner against sources from an older working change. Production uses current +`main`'s service schema and deployment tooling.