umami-software/umami — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでプライバシー重視の自社ホスト型アナリティクスプラットフォーム。クッキーなしでトラフィック・キャンペーン・ユーザー行動を一元管理します。

Umamiはセルフホスト可能なプライバシー重視のWebアナリティクス基盤です。トラフィック・キャンペーン・行動・コンバージョン・収益の指標を1つの管理画面にまとめ、クッキーを使わずに収集します。Next.js製アプリとPostgreSQL(またはClickHouse)を組み合わせ、Dockerでも手動ビルドでも起動できます。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

package.jsonのbuildスクリプトはbuild-db(Prisma生成)・build-tracker(計測用JSタグのビルド)・build-recorder・build-geo・build-appを順に実行し、Next.jsの単一アプリとして計測タグ配信・APIサーバー・管理画面ダッシュボードを1つにまとめます。DATABASE_URLで指定したPostgreSQLに対しprisma/migrationsのSQLを適用してテーブルを作成し、初回ビルド時にadmin/umamiの初期ユーザーを自動作成します。db/clickhouse配下にも別途マイグレーションがあり、大量イベントを扱う構成ではClickHouseを併用できる設計です。Dockerfileはビルド用と実行用のステージを分け、Prismaのエンジンバイナリが確実に取り込まれているかをRUN ls...で検証してから、非rootユーザーnextjsで.next/standaloneを起動します。起動後はscripts/start-docker.shがcheck-db・update-tracker・start-serverを順に呼び、DBスキーマ整合性チェックとトラッカースクリプトの更新を行ってからserver.jsを立ち上げます。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
git cloneした後にpnpm installを実行すると、Next.js・Prisma・chart.jsなど多数の依存関係がpnpm-lock.yamlに従ってインストールされます。
STEP 02
`.env`にDATABASE_URLを設定してpnpm run buildを実行すると、check-envとcheck-dbが動きPostgreSQLへの接続確認とテーブル作成が行われます。
STEP 03
初回ビルドが成功すると、管理者アカウントusername:admin、password:umamiが自動作成され、ログイン画面が使えるようになります。
STEP 04
pnpm run startで`http://localhost:3000`が起動し、ダッシュボードから新規サイトを追加すると計測用スクリプトタグが発行されます。
STEP 05
Docker利用時はdocker compose up -dだけでUmami本体とPostgreSQLコンテナが同時に立ち上がり、healthcheckでDB起動を待ってからアプリが起動します。
STEP 06
2段階認証を使う場合はTWO_FACTOR_ENCRYPTION_KEYを64桁の16進文字列として設定しないと機能が有効化されない点に、事前に気づく必要があります。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

実行して得られるのは、自分のサイトに埋め込む計測タグと、それが集めたアクセス・行動・コンバージョン・収益データを見るための管理ダッシュボードです。データは自前のPostgreSQL(または追加でClickHouse)に保存されるため、外部サービスに依存せず手元でアクセス解析基盤を運用できる状態になります。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

READMEにはNode.js 18.18以上とPostgreSQL 12.14以上が必須と明記されており、これらを満たさない環境ではビルド段階でcheck-envに引っかかる可能性があります。

db/clickhouse配下に14件のマイグレーションが存在することから、セッションリプレイやヒートマップなど一部の高度な機能はClickHouse併用が前提になっている可能性があり、PostgreSQLのみの構成では制限が出ると考えられます。

初期パスワードがadmin/umamiで固定されているため、公開環境で運用する場合はビルド直後に必ず変更する運用手順が要ります。

DockerfileにはPrismaエンジンバイナリの取り込み確認や非rootユーザー実行など細かい安全対策が書かれており、独自にビルドを組む場合はこの手順を省略しないよう注意が必要です。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

自社サイトやプロダクトのアクセス解析を、クッキーなし・自前インフラで管理したいチームに向いています。Next.js・Prisma・PostgreSQLという構成に慣れたエンジニアであれば、READMEの手順通りにgit clone、pnpm install、pnpm run buildを行うだけで管理画面と計測タグが揃うところまでは、ファイル構成とスクリプト定義から高い確度で再現可能と判断できます。ただしClickHouse併用時の挙動やセッションリプレイ・ヒートマップなど一部機能の実際の完成度は、提供された資料だけでは断定できないため、その部分は導入前に公式ドキュメントで確認するのが安全です。