Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 41 additions & 12 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
name: Docker

on:
workflow_dispatch:

push:
branches:
- master
pull_request:

permissions:
contents: read
Expand All @@ -30,20 +29,50 @@ jobs:
- name: Checkout
uses: actions/checkout@v7

- name: Validate compose build baseline
run: make build
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v4

docs:
name: Docs
- name: Build image (fetches the pinned Neko commit from VERSION)
run: make build-chromium

- name: Test image
run: make test-docker

- name: Login to DockerHub
if: github.ref == 'refs/heads/master'
uses: docker/login-action@v4
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}

- name: Push image
if: github.ref == 'refs/heads/master'
run: make push-chromium

release:
name: Release
needs: build
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
runs-on: ubuntu-latest
permissions:
contents: write

steps:
- name: Checkout
uses: actions/checkout@v7

- name: Validate docs
- name: Create release
env:
GH_TOKEN: ${{ github.token }}
run: |
test -f README.md
test -f docker-compose.yml
test "$(cat CLAUDE.md)" = "@AGENTS.md"
! grep -Eiq 'slack|join\.slack|gitter|badgen\.net' README.md
. ./VERSION
gh release view "$VERSION" || gh release create "$VERSION" --generate-notes

docs:
name: Docs
needs: build
if: github.ref == 'refs/heads/master'
uses: dockette/.github/.github/workflows/dockerhub-description.yml@master
secrets: inherit
with:
image: "dockette/neko"
27 changes: 20 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,31 @@

## Project

Dockette Neko is a Docker Compose wrapper around the upstream Neko virtual browser, with Chrome DevTools Protocol and Playwright MCP ports documented in `docker-compose.yml`.
Dockette Neko builds and publishes `dockette/neko:chromium` (the Neko virtual browser from a fork with Chrome DevTools Protocol and Playwright MCP support) and ships a Docker Compose file that runs it.

There is no Dockerfile here. CI fetches the fork `holyfork/m1k1o-neko` at a pinned commit and builds the image with the fork's own `./build` script.

## Versioning

- `VERSION` holds the release date and `NEKO_REF`, the full commit sha of the fork.
- `make release` sets the date to today (UTC); `make version` prints it.
- To update Neko, put a new full commit sha in `NEKO_REF` and run `make release`.
- Tags: `chromium` and `chromium-<VERSION>`, no `latest`.

## Development

- Use `docker compose config` for safe validation.
- Use `make test` for compose validation.
- Use `make build` only for the local compose baseline; this repository does not build a local Dockerfile in CI.
- Use `make run` or `docker compose up` to start the stack locally.
- Keep upstream Neko clone/build helpers out of CI unless they are intentionally hardened for network access.
- `make test` validates `docker-compose.yml`.
- `make build-chromium` fetches the pinned commit and builds the image (slow).
- `make test-docker` checks that Chromium runs in the built image.
- `make run` starts the stack.

## CI

- Pull requests build and test but never push. On master the image is pushed, a GitHub release is created and the Docker Hub description is synced.
- The fork is fetched over HTTPS at the exact `NEKO_REF` commit, never with `git pull` or SSH. Keep it that way.
- The chromium image is built on the `neko/base` image built in the same run, not on a pulled `ghcr.io` image.

## Maintenance

- Preserve this repository as a compose wrapper unless the Docker image strategy changes.
- Do not add Slack badges.
- Keep README badges aligned with `dockette/copybara` style.
45 changes: 32 additions & 13 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
# Include variables
include VERSION
include .env.dist
-include .env
export

.PHONY: build
build:
docker compose config
# Upstream Neko fork, pinned by commit in VERSION (NEKO_REF)
NEKO_REPO=https://github.com/holyfork/m1k1o-neko.git
NEKO_DIR=.tmp/neko

# Two tags: chromium and chromium-<date>. There is no `latest`.
DOCKER_CHROMIUM_VERSIONED_IMAGE=${DOCKER_CHROMIUM_IMAGE}-${VERSION}

.PHONY: test
test:
Expand All @@ -23,22 +27,37 @@ up:
enter:
docker exec -it neko bash

# Fetch the exact NEKO_REF commit over HTTPS (no branch, no git pull)
.PHONY: download
download:
@if [ -d ".tmp/neko" ]; then \
cd .tmp/neko && git pull; \
else \
git clone https://github.com/holyfork/m1k1o-neko.git .tmp/neko; \
fi
rm -rf ${NEKO_DIR}
git init -q ${NEKO_DIR}
git -C ${NEKO_DIR} fetch -q --depth 1 ${NEKO_REPO} ${NEKO_REF}
git -C ${NEKO_DIR} checkout -q FETCH_HEAD

# Upstream ./build: the base image first, then the chromium app on top of it
.PHONY: build-chromium
build-chromium:
cd .tmp/neko && \
./build -y -r neko
cd .tmp/neko && \
./build -y -a chromium -r neko
build-chromium: download
cd ${NEKO_DIR} && PLATFORM=${DOCKER_PLATFORM} ./build -y -r neko
cd ${NEKO_DIR} && PLATFORM=${DOCKER_PLATFORM} ./build -y -a chromium -r neko
docker tag neko/chromium ${DOCKER_CHROMIUM_IMAGE}
docker tag neko/chromium ${DOCKER_CHROMIUM_VERSIONED_IMAGE}

# Smoke test: chromium runs in the image
.PHONY: test-docker
test-docker:
docker run --rm --platform ${DOCKER_PLATFORM} --entrypoint chromium ${DOCKER_CHROMIUM_IMAGE} --version

.PHONY: push-chromium
push-chromium:
docker push ${DOCKER_CHROMIUM_IMAGE}
docker push ${DOCKER_CHROMIUM_VERSIONED_IMAGE}

.PHONY: version
version:
@echo ${VERSION}

.PHONY: release
release:
@sed -i.bak "s/^VERSION=.*/VERSION=$$(date -u +%Y.%m.%d)/" VERSION && rm VERSION.bak
@cat VERSION
30 changes: 26 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,16 +43,38 @@ docker compose up

6. Profit.

## Versions

Tags on [Docker Hub](https://hub.docker.com/r/dockette/neko):

- `chromium` - the latest build
- `chromium-YYYY.MM.DD` - the build released on that date (for example `chromium-2026.11.09`)

There is no `latest` tag. Every build is published as a [GitHub release](https://github.com/dockette/neko/releases) named after its date.

The image is built from [`holyfork/m1k1o-neko`](https://github.com/holyfork/m1k1o-neko) commit `7704fcc41399506fe91274b14e6473e100a949e9`, pinned by `NEKO_REF` in [`VERSION`](./VERSION). The fork is based on upstream n.eko `master` after `v3.2.0` (Debian 13 images), plus 9 fork commits (Chrome DevTools Protocol, chrome-mcp and playwright-mcp).

To run a fixed build, set the image in your environment:

```bash
DOCKER_CHROMIUM_IMAGE=dockette/neko:chromium-2026.11.09 docker compose up
```

## Development

This repository is a Compose wrapper. CI validates the Compose configuration and does not clone or build upstream Neko.
CI clones the pinned fork commit, builds the image for `linux/amd64`, smoke tests it and, on `master`, pushes both tags and creates the release.

```bash
make test
make build
make run
make test # validate docker-compose.yml
make build-chromium # fetch the pinned NEKO_REF and build the image (slow)
make test-docker # check that Chromium runs in the image
make run # start the stack
make version # print VERSION
make release # set VERSION to today (UTC)
```

To update Neko, put a new full commit sha into `NEKO_REF` in `VERSION` and run `make release`.

## Maintenance

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.
2 changes: 2 additions & 0 deletions VERSION
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
VERSION=2026.11.09
NEKO_REF=7704fcc41399506fe91274b14e6473e100a949e9
Loading