umami-setup

---

name: umami-setup description: "Add Umami self-hosted analytics to any website with adblocker-proof proxy. Covers: creating the website in Umami, setting up a same-domain proxy (Next.js, Astro/Vercel, Caddy, Nginx), and verifying tracking works." homepage: "https://casys.ai" source: "https://github.com/Casys-AI/casys-pml-cloud" author: "Erwan Lee Pesle (superWorldSavior)" always: false privileged: false

---

umami-setup — Add analytics to a new website

Overview

Self-hosted Umami analytics with a same-domain proxy to bypass adblockers. The script is served from the same domain as your site, so blockers see it as first-party.

Prerequisites

A running Umami instance (self-hosted, e.g. analytics.casys.ai)

Admin credentials for Umami

Access to the website's codebase for proxy configuration

Step 1: Create the website in Umami

# Login
TOKEN=$(curl -s -X POST "https:///api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":""}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")
Create website
curl -s -X POST "https:///api/websites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"","domain":""}' | python3 -m json.tool

Save the id from the response — that's your data-website-id.

Step 2: Set up the proxy

The proxy serves the Umami script and send endpoint from your own domain. Adblockers can't distinguish it from your own assets.

Pick the method matching your stack:

Next.js (rewrites in next.config.ts)

// next.config.ts
const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/u/script.js",
        destination: "https:///script.js",
      },
      {
        source: "/u/api/send",
        destination: "https:///api/send",
      },
    ];
  },
};

Then add to your layout:

Astro + Vercel (rewrites in vercel.json)

{
  "rewrites": [
    {
      "source": "/u/script.js",
      "destination": "https:///script.js"
    },
    {
      "source": "/u/api/send",
      "destination": "https:///api/send"
    }
  ]
}

Then add before in your layout(s):

Caddy (reverse proxy)

example.com {
    handle /u/script.js {
        rewrite * /script.js
        reverse_proxy https:// {
            header_up Host 
        }
    }
    handle /u/api/send {
        rewrite * /api/send
        reverse_proxy https:// {
            header_up Host 
        }
    }
}

Nginx

location /u/script.js {
    proxy_pass https:///script.js;
    proxy_set_header Host ;
}
location /u/api/send {
    proxy_pass https:///api/send;
    proxy_set_header Host ;
}

Step 3: Verify

1. Deploy the proxy config 2. Visit your site in a browser 3. Check Umami dashboard — you should see a pageview within seconds 4. Test with adblocker enabled — visit again with uBlock Origin on; the pageview should still appear 5. Verify the proxy works: curl -sI https:///u/script.js should return 200

Proxy path convention

Use /u/ as the proxy prefix. It's short, non-obvious to blockers, and consistent across projects:

| Project | Proxy path | Umami host | |---------|-----------|------------| | thenocodeguy.com | /umami/script.js | analytics.casys.ai | | casys.ai | /u/script.js | analytics.casys.ai |

Umami API — quick reference

# Get all websites
curl -s -H "Authorization: Bearer $TOKEN" "https:///api/websites"
Get stats for a website (last 24h)
START=$(($(date +%s) * 1000 - 86400000))
END=$(($(date +%s) * 1000))
curl -s -H "Authorization: Bearer $TOKEN" \
  "https:///api/websites//stats?startAt=$START&endAt=$END"
Get pageviews
curl -s -H "Authorization: Bearer $TOKEN" \
  "https:///api/websites//pageviews?startAt=$START&endAt=$END&unit=day"

Notes

The Umami instance should be behind a reverse proxy with HTTPS (e.g. Cloudflare → Caddy → localhost:3002)

Docker bind on 127.0.0.1 only — never expose Umami directly to the internet

The /u/ prefix can be anything — /stats/, /t/, etc. — as long as it doesn't conflict with existing routes

A running Umami instance (self-hosted, e.g. analytics.casys.ai)

Admin credentials for Umami

Access to the website's codebase for proxy configuration

The Umami instance should be behind a reverse proxy with HTTPS (e.g. Cloudflare → Caddy → localhost:3002)

Docker bind on 127.0.0.1 only — never expose Umami directly to the internet

The /u/ prefix can be anything — /stats/, /t/, etc. — as long as it doesn't conflict with existing routes