Hajimari: a start page that discovers your Kubernetes apps

A front door for a cluster you already run

Hajimari is described as a beautiful and customizable browser startpage and dashboard with Kubernetes application discovery. The README expands on that: a simplistically beautiful startpage designed to be the entrypoint for your self hosted Kubernetes cluster.

That framing sets the scope precisely. This is not a monitoring system and not a service catalogue with a database. It is a landing page that knows what your cluster is running and shows it to you when you open a browser. The name and the tagline reinforce the intent, Hajimari meaning the beginning of a pleasant experience.

The feature list is short enough to read in one pass. Web and app search with customizable search providers. Dynamically listing apps discovered from Kubernetes Ingresses or Custom Resources. Display of replica status for ingress endpoints. Support for non Kubernetes apps via a custom apps config. A customizable list of bookmarks. Selectable themes with custom theme support. Automatic light and dark mode. Custom configuration overrides per user and browser. And multiple instance support.

The interesting item for a platform engineer is the discovery one, because it is the difference between a bookmark file and a dashboard that stays current. Everything else on the list is presentation. The discovery is what makes the page accurate after you deploy something new at three in the morning and nobody updated a README.

The repository layout shows a two part application. There is a cmd directory with the main entry point, an internal directory for the server logic, a frontend directory for the React side, a charts directory holding the Helm chart, a Dockerfile, a Makefile, a config.yaml.example and an .air.toml for the hot reload tool. The Go module is github.com/toboshii/hajimari and the primary language is Go, with a separate frontend build.

Discovery runs through annotations on your Ingresses

Hajimari looks for specific annotations on Ingresses, and the table in the README lists every one of them with whether it is required.

Only one is required. The hajimari.io/enable annotation, with the value true, marks the ingress of the app you want to show. The rest are optional and are there to shape how the app appears.

The hajimari.io/icon annotation takes an icon name from the MDI icons set, and hajimari.io/appName gives the application a custom name when you do not want to use the name of the ingress. hajimari.io/group sets a custom group name, which is how an app shows in a different group than the namespace it runs in. hajimari.io/instance is a comma separated list of the Hajimari instances where the app should appear, which is what makes the multiple instance support work. hajimari.io/url is a URL that overrides the ingress URL and it must begin with a scheme, either http:// or https://. hajimari.io/targetBlank decides whether links open in new tabs or windows, and hajimari.io/info is a short description of the app.

Two of these annotations are worth pausing on.

The group annotation is the one that changes the shape of the page. By default the app group is the namespace, which is a reasonable default but ties your navigation to your deployment topology. The override exists because the two are different concepts and teams want them different.

The instance annotation is a consequence of a design decision. Hajimari supports multiple instances, and rather than letting two instances fight over the same list, an app declares which instances should show it. That is more explicit than a shared label selector and it puts the choice next to the workload, but it also means every app that should appear in two places has to be annotated twice.

The README also states that Hajimari lists apps discovered from Custom Resources as well as Ingresses, and the display of replica status for ingress endpoints comes from EndpointSlice access, which is why the RBAC requirements mention both.

Installation through Helm, and the release gap in the chart

The Helm install is three commands, adding the chart repository, updating it, and installing the chart:

`helm repo add hajimari https://hajimari.io`
`helm repo update`
`helm install hajimari hajimari/hajimari`

The chart documentation lives in the charts/hajimari directory of the repository, and the RBAC template it references is at charts/hajimari/templates/rbac.yaml. That file matters, because the README states plainly that Hajimari needs access to a kubeconfig file for a service account with access to ingress and endpoint slice objects. If the service account cannot list those, the page renders empty and there is no error message telling you why.

The release history is the thing to check. The listed releases are hajimari-helm-chart-2.0.2 from 2022-10-04, v0.3.1 from 2022-10-03, and hajimari-helm-chart-2.0.1 from 2022-10-03. So the chart versions and the application versions are tracked separately, and the newest tagged artefacts in the list are from October 2022.

Against that, the repository itself is not archived and the last push was on 2026-10-20. The source has moved on considerably since the chart was tagged. What that means in practice is that the chart in the repository may or may not match the source in the repository, and neither obviously matches what the chart repository at hajimari.io serves today. Before you install, compare the chart version the repo serves against the configuration options the README documents, because the configuration table is long and a stale chart will silently ignore the newer keys.

For a local build, the README gives a make based path with a development variant:

make deps
make build

make deps
make dev

You will need go 1.19 and node 18 installed. The Makefile shows what those targets do: deps runs npm install inside the frontend directory, build runs the frontend build and then compiles the Go binary with go build into ./bin/hajimari, and dev runs the backend under air and the frontend dev server in parallel with a three second delay so the backend is up first.

The configuration surface is wide and partly redundant

The configuration table in the README is the reference for the whole feature set, and it is worth reading in full because several of the options are not what their names suggest.

instanceName names the Hajimari instance, defaulting to an empty string, and it pairs with the hajimari.io/instance annotation on the app side. defaultEnable, default false, exposes all ingresses in selected namespaces without needing the enable annotation on each one, which is convenient for a cluster where every ingress is a real app. namespaceSelector combines hardcoded namespaces with label selectors and defaults to any: true, and it is the second half of the defaultEnable behaviour.

Then there are the display options. name, default You, is the name used in the greeting. title, default Hajimari, is the browser title. lightTheme and darkTheme, default gazette and horizon, select the theme for each browser preference, with the note that custom themes go in the customThemes list. showGreeting toggles the greeting and date, showAppGroups toggles grouping apps by group, that is by namespace, showAppUrls toggles displaying app URLs, and showAppInfo toggles showing app info, which is off by default.

The configuration can be modified by either a ConfigMap or values.yaml if you are using Helm, which is a nice touch, and the per user and browser overrides are a separate mechanism on top of it, so the same instance can present differently to different people without running two deployments.

The repository also ships a config.yaml.example at the top level, which is the local development counterpart to the ConfigMap. The Makefile has no target that references it directly, so the wiring between the example file and the running binary is in the application code rather than the build.

The one real inconsistency in the documentation is the lightTheme and darkTheme description, where the dark theme row reads brwoser rather than browser. It is a typo in a table that people copy from, and it is a small signal about how actively the documentation is reviewed.

How the Go service is put together

The dependency list in go.mod describes the shape of the backend better than the README does.

The HTTP layer is chi, the router from the chi project, with its cors and render middleware packages, and logrus for logging, wrapped by chi-middleware/logrus-logger. Configuration comes from viper, with yaml.v3 for the file format and mapstructure for decoding. File watching uses fsnotify, which is how the config and app list stay current without a page reload, and nanoid is there for generating identifiers. The Kubernetes client is client-go with the api and apimachinery modules, pinned at 0.25.2.

That Kubernetes version is worth noticing. The module targets k8s.io/api v0.25.2, which is a specific minor release of the client libraries, and a client-go that old talking to a modern cluster is where version skew problems live. The go.mod also declares go 1.19, matching the Go version the README asks for, and the README badge shows Go v1.19 as well.

The Dockerfile shows the build in three stages. A node:16.20-alpine stage runs npm install and npm run build for the frontend, a golang:1.20.2-alpine stage copies that build output in, downloads the Go modules and compiles a static binary with the netgo tag, and a final alpine:3.17 stage carries only the binary, with a non-root hajimari user and tini as the entrypoint so signals are handled properly. The build is cross-compiled from the TARGETPLATFORM build argument, and CGO is disabled.

Note the mismatch between the Go version in the Dockerfile, 1.20.2, and the version the README and go.mod ask for, 1.19. It is harmless in practice, since a 1.20 toolchain builds a 1.19 module, but it is the kind of drift that tells you the container image and the documented toolchain are maintained separately.

Where Hajimari is the wrong tool

The obvious limitation is the discovery mechanism. If a service is not exposed through an Ingress or a Custom Resource, Hajimari cannot find it, and the fallback is the custom apps config, which means you are back to maintaining a list by hand for exactly the services that discovery was supposed to cover. For a cluster that is mostly internal workloads with no Ingress at all, that is most of the estate.

The second limitation is what it is not. There is no uptime check, no latency measurement, no log access and no deployment status beyond the replica count shown for ingress endpoints. If you were hoping for a dashboard that tells you whether something is healthy, Hajimari will not do that, and the name dashboard invites the wrong assumption.

The third is the version gap I mentioned earlier, and it is the one most likely to cost you an afternoon. The listed chart releases are from 2022 while the source is four years newer. The configuration table in the README documents many options, and if the chart you install is older than the source you are reading, some of those options will have no effect. The symptom is a setting that is accepted and ignored.

The alternatives differ in what they require of the cluster. A plain bookmark or start page needs nothing from Kubernetes and breaks nothing when an app moves, and for a handful of services that is the right answer. A monitoring dashboard built on the Prometheus and Grafana stack tells you which endpoints are actually responding, which is a different and arguably more valuable question than which ingresses exist, at the cost of running and maintaining that stack. A service catalogue built as part of an internal developer portal can carry ownership, documentation links and deployment history, which Hajimari has no concept of, since its model is a link and an icon.

The real alternative, though, is the one Hajimari is explicitly displacing: the wiki page, the README file or the bookmark bar that lists what is deployed. Hajimari's argument is that a list maintained by hand is wrong within a week, and that is a fair argument for a cluster where services are added often. If your cluster changes rarely, the hand maintained list is cheaper and never has a stale chart version problem.

Licence, community and what to check before deploying

The licence is Apache-2.0, with the LICENSE file at the repository root, which is the usual choice for infrastructure software that people are expected to modify and self host. The README links a Discord server for support and a GitHub Actions CI badge for the build, and the homepage is hajimari.io, which is also where the Helm chart repository is served from.

On maintenance, the picture is mixed and worth being precise about. The repository is not archived and the last push was on 2026-10-20, so the source is actively worked on. The listed releases, however, are the chart 2.0.2 and 2.0.1 plus application v0.3.1, all from October 2022, and the README's configuration table describes a feature set that has clearly grown since. A project can be alive in its repository and still be distributed as an old chart, and the two facts are not in conflict.

That is the single most important thing to verify before you deploy. Compare the values in the chart you are about to install against the configuration table in the README, and if they disagree, build from source instead. The local build path is documented and the Makefile is small, so that is a reasonable fallback.

The second check is the service account. The RBAC template at charts/hajimari/templates/rbac.yaml governs the Ingress and EndpointSlice access that the whole discovery feature depends on. If the account is missing one of those permissions, the page renders without apps and there is no obvious error. Confirm the account can list both object types before you conclude the tool is broken.

The third check is the annotation coverage. The default of defaultEnable being false means every app you want listed needs hajimari.io/enable set to true, and the group and instance overrides need to be applied deliberately. Audit the Ingress objects in a namespace and confirm the ones you expect to see carry the annotations.

The last practical point is the version skew in the Kubernetes client libraries, pinned at 0.25.2. If your cluster runs a much newer Kubernetes, the discovery path is the thing most likely to behave differently from what the README describes, and it is worth testing against a namespace you do not mind if it goes wrong.

Editorial conclusion

Adopt Hajimari if you run a self hosted Kubernetes cluster and want a single front door for its applications, with discovery driven by Ingress annotations rather than a hand maintained list. Do not adopt it if your services are not exposed through Ingresses or Custom Resources, since the discovery mechanism depends on them, and be careful with the Helm chart, whose listed releases date from 2022. Verify first that your service account has the Ingress and EndpointSlice access the RBAC template grants, that the annotations you plan to use are set on the objects you want listed, and that the chart version you install matches the source you are reading.

Frequently asked questions

Official sources

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