umami-setup

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, As...

Security Scan

The skill is an instruction-only guide to add Umami with a same-domain proxy; its instructions, required inputs, and scope are consistent with that purpose.

Purpose & Capability

The README-style SKILL.md describes creating a website in Umami and configuring same-domain proxy rewrites for Next.js/Astro/Vercel/Caddy/Nginx. All required capabilities (Umami instance, Umami admin credentials, and access to the website codebase) are consistent with the described functionality. The skill does not request unrelated cloud credentials or binaries.

Instruction Scope

Instructions are explicit and limited to actions necessary for the task: performing the Umami API login, creating a website via the API, configuring proxy rewrites/reverse-proxy rules, and verifying tracking. The instructions do not instruct reading unrelated system files or transmitting data to third-party endpoints beyond the Umami host and the user's domain.

Install Mechanism

This is instruction-only with no install spec and no code files; nothing is written to disk or fetched automatically, which minimizes install-time risk.

Credentials

The skill does not declare required env vars, but its steps require Umami admin credentials and knowledge of the Umami host and website codebase — these are expected and proportional. These credentials are sensitive (they produce bearer tokens used to create websites); the user should avoid sharing them and run commands in a trusted environment.

Persistence & Privilege

always:false and no install actions mean the skill does not persist or request elevated platform privileges. It will not be permanently present or modify other skills/configurations.

Assessment

This is a how-to guide you will follow manually. Before proceeding: ensure the Umami instance you use is trusted; run the provided curl commands in a secure terminal (they require admin username/password and will return a sensitive bearer token); avoid pasting credentials into third-party or shared consoles; deploy the reverse proxy with HTTPS and limit direct exposure of the Umami backend (bind to localhost or restrict by firewall); verify Host header handling and CORS on your proxy so you don't accidentally forward internal hostnames or auth headers; test changes in a staging environment first and confirm pageviews while using an adblocker. If you prefer automation, consider creating limited-scope API credentials rather than using the Umami admin account where possible.

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://<UMAMI_HOST>/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"<PASSWORD>"}' \
  | python3 -c "import json,sys; print(json.load(sys.stdin)['token'])")

# Create website
curl -s -X POST "https://<UMAMI_HOST>/api/websites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"<SITE_NAME>","domain":"<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://<UMAMI_HOST>/script.js",
      },
      {
        source: "/u/api/send",
        destination: "https://<UMAMI_HOST>/api/send",
      },
    ];
  },
};

Then add to your layout:

<script defer src="/u/script.js" data-website-id="<WEBSITE_ID>"></script>

Astro + Vercel (rewrites in vercel.json)

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

Then add before </head> in your layout(s):

<script defer src="/u/script.js" data-website-id="<WEBSITE_ID>"></script>

Caddy (reverse proxy)

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

Nginx

location /u/script.js {
    proxy_pass https://<UMAMI_HOST>/script.js;
    proxy_set_header Host <UMAMI_HOST>;
}
location /u/api/send {
    proxy_pass https://<UMAMI_HOST>/api/send;
    proxy_set_header Host <UMAMI_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://<YOUR_DOMAIN>/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://<UMAMI_HOST>/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://<UMAMI_HOST>/api/websites/<WEBSITE_ID>/stats?startAt=$START&endAt=$END"

# Get pageviews
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://<UMAMI_HOST>/api/websites/<WEBSITE_ID>/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