Add Umami web analytics example - #296
Open
tjmgregory wants to merge 4 commits into
Open
Conversation
Deploys Umami v3.0.3 as a Next.js standalone app on a FROM scratch image, backed by the existing postgres example. Includes a workaround for the missing pgcrypto extension (not needed on PG16+). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
tjmgregory
marked this pull request as draft
April 15, 2026 16:12
- cd back to ../umami/ after postgres deploy (not examples/umami/) - Note macOS sed -i '' syntax difference for pgcrypto patch Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Location tracking is one of Umami's key features. Stripping it saved 54 MB but isn't worth the loss in functionality. Users who need a smaller image can add the rm line back. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The 386 MB image (with GeoIP data) OOMs at 1024 MiB during initramfs unpacking. 1536 MiB works reliably. Document the 1024 MiB option for users who strip GeoIP. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds an Umami v3.0.3 analytics example backed by PostgreSQL.
Changes:
- Builds a scratch-based Umami image.
- Adds Unikraft runtime configuration.
- Documents migrations, deployment, upgrades, and cleanup.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Summary |
|---|---|
umami/README.md |
Moderate (3 votes): kraft cloud deploy omits /tls+http. Moderate (3 votes): Upgrade instructions leave migration version hardcoded to v3.0.3. Nit (3 votes): Sequential migration commands resolve the build path incorrectly. Nit (2 votes): APP_SECRET fallback behavior is documented incorrectly. Nit (3 votes): geo retention conflicts with documented image size and memory. Nit (2 votes): Missing entry in the repository root README catalog. |
umami/Kraftfile |
Adds Unikraft runtime and startup configuration. |
umami/Dockerfile |
Builds Umami as a minimal scratch-based image. |
umami/.dockerignore |
Excludes Unikraft build artifacts. |
Suppressed comments (4)
umami/Dockerfile:32
- The final stage never sets a working directory, so the absolute Kraftfile command will start Node with
/as its cwd. Umami v3.0.3 resolves the GeoLite database aspath.join(process.cwd(), 'geo'), while this image puts it under/app/geo; location lookups will therefore fail. Set the final-stage working directory to/app.
FROM scratch
umami/Kraftfile:7
- Launching
/app/server.jsbypasses Umami'sstart-dockerwrapper. In v3.0.3 that wrapper runsupdate-tracker, which rewrites/api/sendinpublic/script.jswhenCOLLECT_API_ENDPOINTis set; the README advertises this variable, so the served tracker will still post to/api/send. Either include and invoke the wrapper or remove/document this unsupported option.
cmd: ["/usr/bin/node", "/app/server.js"]
umami/README.md:43
- These default PostgreSQL commands create
PGDATAon the instance filesystem and mount no volume, so recreating the database VM loses all Umami analytics data. Please add the postgres example's volume setup to both deployment commands or explicitly label this as an ephemeral demo.
unikraft run --metro=fra -p 5432:5432/tls -m 1536M -e POSTGRES_PASSWORD=<password> -e POSTGRES_DB=umami --scale-to-zero=off <my-org>/postgres:latest
umami/README.md:141
- Because the
Kraftfilestarts/app/server.jsdirectly, Umami's normalstart-dockersequence (which runsupdate-tracker.js) is never executed. SettingCOLLECT_API_ENDPOINTtherefore does not update the shippedpublic/script.js; only manually sent requests are rewritten, so the documented custom tracker endpoint does not work as described. Add a startup step to update the tracker or remove/qualify this variable.
| `COLLECT_API_ENDPOINT` | No | Custom tracker endpoint path (replaces `/api/send`) |
馃挕 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| Return to the `umami/` example directory and deploy: | ||
|
|
||
| ```bash title="unikraft" | ||
| cd ../umami/ |
| ```bash title="kraft" | ||
| cd ../umami/ | ||
| kraft cloud deploy \ | ||
| -p 443:3000 \ |
|
|
||
| To upgrade to a new Umami release: | ||
|
|
||
| 1. Update `UMAMI_VERSION` in the `Dockerfile` (e.g., `v3.0.3` to `v3.1.0`) |
| | Variable | Required | Description | | ||
| |----------|----------|-------------| | ||
| | `DATABASE_URL` | Yes | PostgreSQL connection string | | ||
| | `APP_SECRET` | Recommended | Secret for session encryption. Auto-generated if not set, but won't persist across restarts. | |
|
|
||
| ## Notes | ||
|
|
||
| - **Image size**: The `FROM scratch` image is ~386 MB (including GeoIP data for visitor location tracking). Umami requires at least 1536 MiB of memory to unpack the initramfs and run. To reduce the image by ~54 MB (and lower the minimum memory to 1024 MiB), add `rm -rf /app/.next/standalone/geo` to the `Dockerfile` build stage. This disables visitor location tracking. |
| @@ -0,0 +1,186 @@ | |||
| # Umami Web Analytics | |||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
umami/example deploying Umami v3.0.3 open-source web analyticspostgres/example as the database backendFROM scratchfinal stage following the same pattern ashttpserver-node21-nextjspgcryptoextension (not needed on PG16+ which hasgen_random_uuid()built-in)Files
umami/Kraftfilenode /app/server.jsumami/Dockerfileumami/README.mdumami/.dockerignore.unikraft/build artifactsTested on
frapostgres/example馃 Generated with Claude Code