feat: dev container support (#734)

* chore: add devcontainer for Anubis

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore(devcontainer): ensure user can write to $HOME

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore(devcontainer): forward ports, add launch config

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore(devcontainer): add playwright deps

Signed-off-by: Xe Iaso <me@xeiaso.net>

* docs: document devcontainer usage

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore: spelling

Signed-off-by: Xe Iaso <me@xeiaso.net>

* ci(devcontainer): fix action references

Signed-off-by: Xe Iaso <me@xeiaso.net>

* chore(devcontainer): fix ko on arm64

Signed-off-by: Xe Iaso <me@xeiaso.net>

---------

Signed-off-by: Xe Iaso <me@xeiaso.net>

.devcontainer/Dockerfile

@@ -0,0 +1,12 @@
+FROM ghcr.io/xe/devcontainer-base/pre/go
+
+WORKDIR /app
+
+COPY go.mod go.sum package.json package-lock.json ./
+RUN go install github.com/a-h/templ/cmd/templ \
+  && npx --yes playwright@1.52.0 install --with-deps\
+  && apt-get update \
+  && apt-get -y install zstd brotli \
+  && mkdir -p /home/vscode/.local/share/fish \
+  && chown -R vscode:vscode /home/vscode/.local/share/fish \
+  && chown -R vscode:vscode /go

.devcontainer/README.md

@@ -0,0 +1,13 @@
+# Anubis Dev Container
+
+Anubis offers a [development container](https://containers.dev/) image in order to make it easier to contribute to the project. This image is based on [Xe/devcontainer-base/go](https://github.com/Xe/devcontainer-base/tree/main/src/go), which is based on Debian Bookworm with the following customizations:
+
+- [Fish](https://fishshell.com/) as the shell complete with a custom theme
+- [Go](https://go.dev) at the most recent stable version
+- [Node.js](https://nodejs.org/en) at the most recent stable version
+- [Atuin](https://atuin.sh/) to sync shell history between your host OS and the development container
+- [Docker](https://docker.com) to manage and build Anubis container images from inside the development container
+- [Ko](https://ko.build/) to build production-ready Anubis container images
+- [Neovim](https://neovim.io/) for use with Git
+
+This development container is tested and known to work with [Visual Studio Code](https://code.visualstudio.com/). If you run into problems with it outside of VS Code, please file an issue and let us know what editor you are using.

.devcontainer/devcontainer.json

@@ -0,0 +1,34 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/debian
+{
+  "name": "Dev",
+  // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+  "build": {
+    "dockerfile": "./Dockerfile",
+    "context": "..",
+    "cacheFrom": [
+      "type=registry,ref=ghcr.io/techarohq/anubis/devcontainer"
+    ]
+  },
+  "postStartCommand": "npm ci && go mod download",
+  "features": {
+    "ghcr.io/xe/devcontainer-features/ko:1.1.0": {}
+  },
+  "initializeCommand": "mkdir -p ${localEnv:HOME}${localEnv:USERPROFILE}/.local/share/atuin",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "esbenp.prettier-vscode",
+        "ms-azuretools.vscode-containers",
+        "golang.go",
+        "unifiedjs.vscode-mdx",
+        "a-h.templ",
+        "redhat.vscode-yaml"
+      ]
+    }
+  },
+  "forwardPorts": [
+    8923,
+    3000
+  ]
+}

.github/actions/spelling/expect.txt

@@ -13,6 +13,8 @@ asnc
 asnchecker
 asns
 aspirational
+atuin
+azuretools
 badregexes
 bdba
 berr
@@ -48,6 +50,7 @@ chibi
 cidranger
 ckie
 cloudflare
+Codespaces
 confd
 containerbuild
 coreutils
@@ -223,6 +226,7 @@ qwantbot
 rac
 rawler
 rcvar
+redhat
 redir
 redirectscheme
 refactors
@@ -248,6 +252,7 @@ shellcheck
 Sidetrade
 simprint
 sitemap
+skopeo
 sls
 sni
 Sourceware
@@ -277,6 +282,7 @@ Tik
 Timpibot
 traefik
 uberspace
+unifiedjs
 unixhttpd
 unmarshal
 unparseable
@@ -322,4 +328,5 @@ yoursite
 Zenos
 zizmor
 zombocom
+Zonbocom
 zos

.github/workflows/devcontainer.yml

@@ -0,0 +1,47 @@
+name: Dev container prebuild
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*.*.*"]
+
+jobs:
+  devcontainer:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-tags: true
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: latest
+
+      - run: |
+          sudo apt-get update
+          sudo apt-get -y install skopeo
+
+      - name: Log into registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+        with:
+          registry: ghcr.io
+          username: techarohq
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Pre-build dev container image
+        uses: devcontainers/ci@8bf61b26e9c3a98f69cb6ce2f88d24ff59b785c6 # v0.3.1900000417
+        with:
+          imageName: ghcr.io/techarohq/anubis/devcontainer
+          cacheFrom: ghcr.io/techarohq/anubis/devcontainer
+          push: always
+          platform: linux/amd64,linux/arm64

.vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "ms-azuretools.vscode-containers",
+    "golang.go",
+    "unifiedjs.vscode-mdx",
+    "a-h.templ",
+    "redhat.vscode-yaml"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,27 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Package",
+      "type": "go",
+      "request": "launch",
+      "mode": "auto",
+      "program": "${fileDirname}"
+    },
+    {
+      "name": "Anubis [dev]",
+      "command": "npm run dev",
+      "request": "launch",
+      "type": "node-terminal"
+    },
+    {
+      "name": "Start Docs",
+      "command": "cd docs && npm ci && npm run start",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/docs/CHANGELOG.md

@@ -11,8 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Determine the `BIND_NETWORK`/`--bind-network` value from the bind address ([#677](https://github.com/TecharoHQ/anubis/issues/677))
+- Determine the `BIND_NETWORK`/`--bind-network` value from the bind address ([#677](https://github.com/TecharoHQ/anubis/issues/677)).
 - Implement localization system. Find locale files in lib/localization/locales/.
+- Implement a [development container](https://containers.dev/) manifest to make contributions easier.
 - Fix dynamic cookie domains functionality ([#731](https://github.com/TecharoHQ/anubis/pull/731))
 - Add option for custom cookie prefix ([#732](https://github.com/TecharoHQ/anubis/pull/732))
 

docs/docs/developer/local-dev.md

@@ -2,6 +2,10 @@
 title: Local development
 ---
 
+If you use an editor with [Development containers](https://containers.dev) support, load this repo's [devcontainer configuration](https://github.com/TecharoHQ/anubis/tree/main/.devcontainer). Skip to [Running Anubis locally](#running-anubis-locally) if you are using the devcontainer.
+
+This enables you to contribute from [GitHub Codespaces](https://github.com/features/codespaces) or other web-based editors.
+
 :::note
 
 TL;DR: `npm ci && npm run dev`