Tianji: Website Analytics, Uptime Monitoring and Server Status in One TypeScript Stack

The problem Tianji picks: three dashboards for one small site

The README states the motivation directly. Checking a website normally means an analytics tool such as GA or umami for page views and unique visitors, an uptime monitor for connectivity and network quality, and Prometheus for server-reported status. Add a telemetry system if you ship something that other people self-host and want to know how those deployments behave. Four services, four configuration surfaces, four things to upgrade. Tianji's answer is to put those needs in one application and accept less depth in each. The README is explicit about who that suits: users with lightweight needs, not experts who require specialised tooling. That framing matters when you evaluate it, because the project is not claiming parity with any of the tools it replaces. It is claiming that for a small site, the combined install cost of the separate tools is the bigger problem. The repository topics list analytics, uptime, uptime-monitor, uptimekuma, umami, server-status and self-hosted, which matches that positioning.

What the repository actually contains

Tianji is a TypeScript project with a client and a server under src/, a website/ directory holding documentation assets and preview screenshots, and a Docker Compose file at the repository root. The README's roadmap is the clearest inventory of shipped features: website analysis, monitor with passive result reception, server status, problem notification, telemetry, an OpenAPI surface, team collaboration, UTM tracking, waitlist, survey, lighthouse report, hooks, and Helm install support with installation from a public chart. One roadmap item is unchecked, the survey page, so survey exists in the data model but the page for respondents is not finished. The README also credits umami and uptime-kuma as inspirations, both MIT licensed, while Tianji itself is Apache-2.0. That is a normal arrangement for a project that reimplements ideas rather than copying code, but it is worth knowing which parts of the feature set are descended from which tool if you are comparing behaviour.

How the pieces fit: one server, one database, reporters outside

The architecture visible in the material is a single server process backed by PostgreSQL. The Compose stack starts the tianji application and its postgres database together, and the server reads its connection string from DATABASE_URL, with the README's example being postgresql://tianji:tianji@localhost:5432/tianji?schema=public. Website analytics data, monitor results and server status all land in that one database. The monitor side has a detail worth noting: the roadmap marks support for passive reception of results as complete, and a separate reporter release workflow exists in the CI configuration. That means checks can be reported into Tianji from outside rather than only initiated by the server, which is how you monitor endpoints that your own instance cannot reach. The roadmap also lists an uninstall guide and a download-from-server path for the reporter, plus a custom params guide. Those three items are the operational surface you inherit: something has to run on the monitored machine, and it has to be removable and configurable. Server status follows the same pattern, with agents reporting in rather than Tianji scraping hosts. The telemetry feature is the same mechanism pointed at a different audience, letting you collect basic information about how other people deployed your software. The README even embeds a Tianji visitor badge served from tianji.moonrailgun.com, which is the project using its own telemetry endpoint on its own repository.

Getting it running: Compose first, source second

The documented path is short. From the repository root, run docker compose up -d. That starts the application and PostgreSQL, and the README gives the default address as http://localhost:12345. If you want to work on the source instead, copy the example environment file with cp .env.example src/server/.env and set DATABASE_URL to your PostgreSQL connection string. The README states that DATABASE_URL is the minimum configuration and that OPENAPI_KEY is only needed for the translation auto-generation command, not for running the server. Translation work is a separate flow: edit src/client/i18next-toolkit.config.cjs to add a country code, add the display entry in src/client/utils/i18n.ts, then from src/client run pnpm install, pnpm run translation:extract and pnpm run translation:translate. The translate step calls ChatGPT, which is why OPENAPI_KEY is required for it. Generated files land in src/client/public/locales and the README tells you to check them manually. Note the naming: the variable is OPENAPI_KEY, not an OpenAI key name, so copy it exactly from the README. Beyond Compose, the README lists one-click deployment buttons for Hostinger, Sealos, RepoCloud, Render and ClawCloud, and the roadmap marks Helm install support including installation from a public chart as done.

Where Tianji is the wrong tool

The README's own framing is the honest limitation: Tianji targets lightweight needs and says so. If your requirement is Prometheus-grade metric collection with PromQL queries, recording rules and a mature alerting ecosystem, Tianji's server status feature is not a substitute, and the README does not present it as one. It reports status; it does not offer a query language over time series. The same applies to analytics depth. A team that needs funnels, cohort retention, session stitching across domains or warehouse export will hit the ceiling quickly, because the README describes page views, unique visitors and per-page visit counts as the analytics scope. There is also a concentration risk in the single-database design: analytics events and monitor results share one PostgreSQL instance, so a heavy analytics write load and your uptime history compete for the same resources. The repository does not describe a separate time-series store or a retention policy for old events, so plan your own backup and retention strategy around that database. Finally, the survey feature is half-finished by the project's own roadmap, with the respondent-facing page unchecked. Do not adopt Tianji for surveys today.

Tianji against running umami and Uptime Kuma separately

The obvious alternative is the combination the README names: umami for analytics and uptime-kuma for monitoring, both MIT licensed, each doing one job. The difference in approach is scope versus focus. Umami is an analytics application; its data model, UI and query surface are built around page views and visitor metrics, and it does nothing about uptime. Uptime Kuma is a monitor; it schedules checks and alerts, and it does not collect page views or server metrics. Running both gives you two databases or two storage backends, two upgrade cycles and two sets of credentials, but each component is maintained by a community focused on that single problem. Tianji trades that specialisation for one install, one database and one place to look. If your monitoring needs are simple and your analytics needs are simple, consolidating removes real operational work. If either need is not simple, the split stack is the better fit even though it costs more to run. The README is candid about this: it says specialisation is good when you are an expert in the related abilities, and that the all-in-one form wins for most users with lightweight requirements.

Maintenance, releases and the licence you inherit

Release cadence is visible from the tags: v1.32.34, v1.32.35 and v1.32.36 arrived within roughly a week in September 2026, so the project ships frequently and you should expect to pin versions rather than track latest. Pinning matters more than usual here because a single container carries analytics, monitoring and status features; an upgrade touches all three at once, and there is no way to upgrade only the monitor component. The Apache-2.0 licence permits commercial use and modification and includes an explicit patent grant, which is a different posture from the MIT licences on umami and uptime-kuma that the README cites as inspirations. Apache-2.0 also requires you to preserve notices and state changes if you redistribute a modified version. If you embed Tianji's telemetry badge or its reporter in software you ship to customers, read the licence text yourself rather than treating this paragraph as advice. The translation pipeline is one maintenance cost that is easy to overlook: adding a language means editing two config files, running three pnpm commands and manually reviewing machine-generated output in src/client/public/locales, and the translate step depends on an external API key.

Editorial conclusion

Adopt Tianji if you are running a small number of self-hosted sites or open source deployments and want page-view analytics, uptime checks and server status behind one Docker Compose stack and one PostgreSQL database. Do not adopt it if you need Prometheus-style metric queries, long-retention time series or an established alerting ecosystem, because the README describes a lightweight all-in-one tool rather than a specialist one. Before committing, run the Compose stack, confirm the default port 12345 is what you expect, and check the reporter uninstall guide and custom params guide in the repository, since the monitor reporter is the component you will have to operate on machines outside your own infrastructure.

Official sources

1. License: Apache-2.0
2. msgbyte/tianji on GitHub
3. Project website
4. README
5. Releases