Docker

Run the Kuma Mieru GHCR image on your own server with Docker Compose or docker run.

Docker deployment is in Beta.

The image is ghcr.io/alice39s/kuma-mieru:1. It supports linux/amd64 and linux/arm64. The service in the container listens on port 3000. The examples below map it to port 3883 on the host. For the meaning of the tags, see Versioning.

Start

Docker Compose is the recommended method.

Clone the repository:

git clone https://github.com/Alice39s/kuma-mieru.git
cd kuma-mieru

docker-compose.yml reads the .env file in the repository root. Copy the template of the web application:

cp apps/web/.env.example .env

Edit .env and set at least UPTIME_KUMA_URLS. For the other variables, see Environment Variables.

.env

UPTIME_KUMA_URLS=https://example.kuma-mieru.invalid/status/your-status-page-id

The template lines KUMA_MIERU_TITLE, KUMA_MIERU_DESCRIPTION and KUMA_MIERU_ICON replace the title, description and icon of the status page. Change the title and the description to the values that you need. To keep the icon of the status page, delete the KUMA_MIERU_ICON line.

Start the service:

docker compose up -d

The service is available at http://0.0.0.0:3883.

Show the logs:

docker compose logs -f

Missing variables in .env become empty values

The environment section of docker-compose.yml lists the status page addresses and the KUMA_MIERU_* variables. If one of them is missing from .env, it goes to the container as an empty value and replaces the built-in default of the image:

If neither UPTIME_KUMA_URLS nor UPTIME_KUMA_BASE_URL with PAGE_ID is set, the configuration script stops with an error and the container start stops.
If KUMA_MIERU_SHOW_STAR_BUTTON is missing, the Star button is hidden. To show it, write KUMA_MIERU_SHOW_STAR_BUTTON=true.
If KUMA_MIERU_TITLE or KUMA_MIERU_DESCRIPTION is missing, the browser tab title and the page description use the Kuma Mieru defaults.
If KUMA_MIERU_ICON is missing, the icon of the status page is used.

Built-in defaults of the image

The image sets defaults for these variables. When you start the container with docker run, each variable that you do not set with -e or --env-file uses its default:

Variable	Default
`UPTIME_KUMA_URLS`	Empty
`UPTIME_KUMA_BASE_URL`	`https://whimsical-sopapillas-78abba.netlify.app`
`PAGE_ID`	`demo`
`KUMA_MIERU_TITLE`	`Uptime Kuma`
`KUMA_MIERU_DESCRIPTION`	`A beautiful and modern uptime monitoring dashboard`
`KUMA_MIERU_ICON`	Empty
`KUMA_MIERU_EDIT_THIS_PAGE`	`false`
`KUMA_MIERU_SHOW_STAR_BUTTON`	`true`
`ALLOW_EMBEDDING`	`false`

If UPTIME_KUMA_URLS is not set, the container uses the built-in UPTIME_KUMA_BASE_URL and PAGE_ID and connects to the demo status page.
The browser tab title and the page description use the environment variables or the built-in values of the image. They do not use the values of the status page. Set KUMA_MIERU_TITLE and KUMA_MIERU_DESCRIPTION to the values that you need. The navigation bar and the multi-page tabs still show the live title of the Uptime Kuma status page first. See Environment Variables.
The built-in KUMA_MIERU_ICON is empty, so the icon of the status page is used.
With the docker-compose.yml of the repository, the variables in its environment section replace these defaults. See the Docker Compose notes above.

Change the configuration

Each time the container starts, it runs the configuration scripts first and then starts the service. After you edit .env, recreate the container to apply the new environment variables:

docker compose up -d --force-recreate

If you use docker run, remove the old container. Then run docker run again with the new options:

docker stop kuma-mieru
docker rm kuma-mieru

Update the image

Run these commands in the repository directory. git pull gets the latest docker-compose.yml:

git pull
docker compose pull
docker compose up -d

Health check

The image has a health check endpoint at /api/health. The Dockerfile and docker-compose.yml both use curl -f to request http://localhost:3000/api/health in the container every 30 seconds, with a timeout of 3 seconds. docker-compose.yml marks the container as unhealthy after 3 failures in a row.

Build the image yourself

If the pulled image has problems, build the image locally. Edit docker-compose.yml: comment out the image line and uncomment the build line:

docker-compose.yml

services:
  kuma-mieru:
    # image: ghcr.io/alice39s/kuma-mieru:1
    build: .

Then build and start:

docker compose up -d --build

The Dockerfile has two stages:

Stage	Content
Build	Based on `node:26.12.1-alpine`. Installs `@kuma-mieru/web` and its workspace dependencies with Bun 1.4.4, then runs `bun run --cwd apps/web build`
Runtime	Based on `node:26.12.1-alpine`. Runs as the non-root user `nextjs` with `dumb-init` as PID 1. At start, `tsx` runs the configuration scripts, then Node.js starts the standalone server

STRICT_IMAGE_REMOTE_PATTERNS applies only when you build the image. See Environment Variables.

Docker

StartCopy Anchor Link

Built-in defaults of the imageCopy Anchor Link

Change the configurationCopy Anchor Link

Update the imageCopy Anchor Link