Add CI rollout baseline

.env.dist

@@ -1,2 +1,13 @@
-LITESTREAM_TEMPLATE=basic
-LITESTREAM_DATA_DIR=/data
+LITESTREAM_TEMPLATE=s3
+LITESTREAM_DB_FILE=/app/data/kuma.db
+LITESTREAM_S3_ENDPOINT=yourbucket.minio.tld
+LITESTREAM_S3_REGION=foobar
+LITESTREAM_S3_BUCKET=foobar
+LITESTREAM_S3_PATH=foobar
+LITESTREAM_S3_ACCESS_KEY_ID=foobar
+LITESTREAM_S3_SECRET_ACCESS_KEY=foobarbaz
+LITESTREAM_RETENTION=24h
+LITESTREAM_RETENTION_CHECK_INTERVAL=1h
+LITESTREAM_SNAPSHOT_INTERVAL=10s
+LITESTREAM_SYNC_INTERVAL=1s
+LITESTREAM_VALIDATION_INTERVAL=12h

.github/workflows/docker.yml

@@ -13,14 +13,37 @@ permissions:
   contents: read
 
 jobs:
+  test:
+    name: "Test"
+    runs-on: "ubuntu-latest"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Set up Docker Buildx"
+        uses: docker/setup-buildx-action@v3
+
+      - name: "Build image"
+        uses: docker/build-push-action@v6
+        with:
+          context: "."
+          load: true
+          tags: "dockette/kumatron:latest"
+
+      - name: "Test image"
+        run: "make test"
+
   build:
     name: "Build"
+    needs: ["test"]
+    if: github.ref == 'refs/heads/master'
     uses: dockette/.github/.github/workflows/docker.yml@master
     secrets: inherit
     with:
-        image: "dockette/kumatron"
-        tag: "${{ matrix.tag }}"
-        context: "${{ matrix.context }}"
+      image: "dockette/kumatron"
+      tag: "${{ matrix.tag }}"
+      context: "${{ matrix.context }}"
     strategy:
       matrix:
         include:
@@ -30,3 +53,20 @@ jobs:
             context: .
 
       fail-fast: false
+
+  docs:
+    name: "Docs"
+    runs-on: "ubuntu-latest"
+    needs: ["build"]
+    if: github.ref == 'refs/heads/master'
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+
+      - name: "Update Docker Hub description"
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: "dockette/kumatron"

AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+## Project
+
+Dockette image for Uptime Kuma with optional Litestream support for streaming SQLite backups to remote storage such as S3.
+
+## Image
+
+- Docker image: `dockette/kumatron`.
+- Build context is the repository root and `Dockerfile` is the only image definition.
+- Runtime base is `louislam/uptime-kuma:1.23.16-debian`.
+- Builder stages download Litestream `v0.3.13` and `envsubst`, then copy them into the runtime image.
+- Runtime data defaults to `DATA_DIR=./data/`; `/app/data` is created by the image.
+- GitHub Actions publishes `latest` and `20250502` from the root context.
+
+## Commands
+
+- `make build` builds `dockette/kumatron:${DOCKER_TAG}`.
+- `make test` starts `kumatron-test` and probes the app with Node over `DOCKER_TEST_PORT`.
+- `make run` starts the image on `${DOCKER_TEST_PORT}:3001` as container `kumatron`.
+- `make enter` opens a shell in the running `kumatron` container.
+- `make test-s3` runs with Litestream S3 environment variables from `.env.dist` and optional `.env`.
+
+## Testing
+
+- Use `make -n build test run` to dry-run the default commands before changing build logic.
+- A real `make test` needs Docker and a built local image; it removes `kumatron-test` on success or failure.
+- Litestream S3 testing needs valid `.env` values and should not commit secrets.
+
+## Guidelines
+
+- Keep `Dockerfile`, `entrypoint.sh`, `litestream/`, `Makefile`, README examples, and `.github/workflows/docker.yml` aligned.
+- Prefer `DOCKER_*` names for Docker-related Makefile variables.
+- Place `.PHONY: <target>` directly above each Makefile target.
+- Preserve Litestream environment variable names because README examples and templates depend on them.
+- Do not introduce unrelated formatting or structural changes.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Makefile

@@ -3,25 +3,49 @@ include .env.dist
 -include .env
 export
 
+DOCKER_IMAGE=dockette/kumatron
+DOCKER_TAG?=latest
+DOCKER_TEST_PORT?=3001
+
+
+.PHONY: build
 build:
-	docker build -t dockette/kumatron .
+	docker build -t ${DOCKER_IMAGE}:${DOCKER_TAG} .
 
+.PHONY: enter
 enter:
 	docker exec -it kumatron bash
 
+.PHONY: test
 test:
+	docker rm -f kumatron-test >/dev/null 2>&1 || true
+	docker run -d --name kumatron-test ${DOCKER_IMAGE}:${DOCKER_TAG}
+	for i in $$(seq 1 60); do \
+		if docker exec kumatron-test node -e "require('http').get('http://127.0.0.1:${DOCKER_TEST_PORT}', (res) => process.exit(res.statusCode >= 200 && res.statusCode < 500 ? 0 : 1)).on('error', () => process.exit(1))"; then \
+			docker rm -f kumatron-test >/dev/null; \
+			exit 0; \
+		fi; \
+		sleep 2; \
+	done; \
+	docker logs kumatron-test; \
+	docker rm -f kumatron-test >/dev/null; \
+	exit 1
+
+.PHONY: run
+run:
 	docker run \
 		-it \
 		--rm \
-		-p 3001:3001 \
+		-p ${DOCKER_TEST_PORT}:3001 \
 		--name kumatron \
-		dockette/kumatron
+		${DOCKER_IMAGE}:${DOCKER_TAG}
 
+.PHONY: test-s3
 test-s3:
 	docker run \
 		-it \
 		--rm \
-		-p 3001:3001 \
+		-p ${DOCKER_TEST_PORT}:3001 \
 		-e LITESTREAM=1 \
 		-e LITESTREAM_TEMPLATE=${LITESTREAM_TEMPLATE} \
 		-e LITESTREAM_DB_FILE=${LITESTREAM_DB_FILE} \
@@ -31,5 +55,10 @@ test-s3:
 		-e LITESTREAM_S3_PATH=${LITESTREAM_S3_PATH} \
 		-e LITESTREAM_S3_ACCESS_KEY_ID=${LITESTREAM_S3_ACCESS_KEY_ID} \
 		-e LITESTREAM_S3_SECRET_ACCESS_KEY=${LITESTREAM_S3_SECRET_ACCESS_KEY} \
+		-e LITESTREAM_RETENTION=${LITESTREAM_RETENTION} \
+		-e LITESTREAM_RETENTION_CHECK_INTERVAL=${LITESTREAM_RETENTION_CHECK_INTERVAL} \
+		-e LITESTREAM_SNAPSHOT_INTERVAL=${LITESTREAM_SNAPSHOT_INTERVAL} \
+		-e LITESTREAM_SYNC_INTERVAL=${LITESTREAM_SYNC_INTERVAL} \
+		-e LITESTREAM_VALIDATION_INTERVAL=${LITESTREAM_VALIDATION_INTERVAL} \
 		--name kumatron \
-		dockette/kumatron
+		${DOCKER_IMAGE}:${DOCKER_TAG}

README.md

@@ -1,5 +1,12 @@
 <h1 align=center>Dockette / Kumatron</h1>
 
+<p align=center>
+   <a href="https://github.com/dockette/kumatron/actions"><img src="https://github.com/dockette/kumatron/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
+   <a href="https://hub.docker.com/r/dockette/kumatron"><img src="https://img.shields.io/docker/pulls/dockette/kumatron.svg" alt="Docker Hub pulls"></a>
+   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
+   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
+</p>
+
 <p align=center>
    🐳 <a href="https://github.com/louislam/uptime-kuma">Uptime Kuma</a> with extra juicy configuration and streaming SQLite.
 </p>
@@ -57,14 +64,15 @@ docker run \
 
 ## Development
 
-See [how to contribute](https://contributte.org/contributing.html) to this package.
-
-This package is currently maintaining by these authors.
+```sh
+make build
+make test
+make run
+make test-s3
+```
 
-<a href="https://github.com/f3l1x">
-    <img width="80" height="80" src="https://avatars2.githubusercontent.com/u/538058?v=3&s=80">
-</a>
+`make test-s3` is a manual S3/Litestream smoke test. Set `LITESTREAM_TEMPLATE=s3` and override the S3 values from `.env.dist` in `.env` before running it.
 
------
+## Maintenance
 
-Consider to [support](https://github.com/sponsors/f3l1x) **f3l1x**. Also thank you for using this package.
+See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider to [support](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.