From 0c140d8732c4b3e915908e6d5c3b033031b8c087 Mon Sep 17 00:00:00 2001 From: clover caruso Date: Tue, 13 Oct 2026 19:57:38 -0700 Subject: [PATCH] Self-host Plausible with Snow SSO for paperclover.net Run Plausible CE with private ClickHouse storage, managed Postgres, disabled outbound email, and an owner session bridge behind Snow forward authentication. Keep anonymous tracker delivery and ingestion available independently of dashboard sign-in. Stage-tested native sessions, role enforcement, CSRF, encoded paths, logout, bootstrap, tracker pageviews and outbound clicks, and parity for all ten supported Cloud import tables. Assisted-by: gpt-6.1-sol --- service/plausible/bootstrap.exs | 54 ++++++ service/plausible/clickhouse-users.xml | 20 ++ service/plausible/clickhouse.xml | 24 +++ service/plausible/service.pkl | 115 +++++++++++ service/plausible/sso-test.exs | 251 +++++++++++++++++++++++++ service/plausible/sso.exs | 176 +++++++++++++++++ tools/plausible.md | 113 +++++++++++ 7 files changed, 753 insertions(+) create mode 100644 service/plausible/bootstrap.exs create mode 100644 service/plausible/clickhouse-users.xml create mode 100644 service/plausible/clickhouse.xml create mode 100644 service/plausible/service.pkl create mode 100644 service/plausible/sso-test.exs create mode 100644 service/plausible/sso.exs create mode 100644 tools/plausible.md 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. -- 2.54.1