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.