docs: a documentation site at openblox.sh (#14)

* docs: a documentation site at openblox.sh

Everything lived in README.md and ARCHITECTURE.md, which were carrying the
pitch, the quick start, the security model and the limitations at once
for audiences that want different things.

Five pages, built with mkdocs-material and deployed to GitHub Pages:
home, quick start, security model, the image contract, contributing.

The security model gets its own page rather than a README section,
because it is the page that decides whether someone adopts a sandboxing
library. It states the threat model, what is isolated and how, and — the
part usually left out — what is NOT claimed: gVisor is not a hypervisor,
side channels are not addressed, revocation is best-effort. It also names
the caller as the weakest link in a default deployment and links the two
issues tracking that.

The image contract was folklore that surfaced as a broken preview. It is
now a page: a shell, a non-root user, and nc-or-python3.

CI builds on pull requests without deploying, so a broken docs build is a
red check rather than a broken site. `mkdocs build --strict` turns a dead
internal link into a failure instead of shipping it.

Emits llms.txt: a large share of readers are agents, and this project's
subject matter is running the code they write.

Docs are markdown in the repository, so a behaviour change and its
documentation move in the same pull request.

* ci: run CI on every pull request, without path filters

main now requires Lint, Test, Integration Tests and the commit-message
check to pass before merge. A skipped check never reports a conclusion,
so with paths-ignore in place a docs-only pull request would sit forever
with four required checks pending and no action available to its author.

Dropping the filter costs a couple of CI minutes on documentation
changes. A category of pull request that silently cannot land costs more.

Side effect worth knowing: Release fires on green CI, so it now also runs
for docs-only commits. It is a no-op there — `docs:` does not bump a
version under conventional commits — but it will appear in the run list
where it previously did not.

Author: Lutherwaves

.github/workflows/ci.yml

@@ -1,18 +1,14 @@
 name: CI
 
+# No paths-ignore. These jobs are required for merge, and a skipped required
+# check never reports — so a docs-only pull request would be unmergeable
+# forever, with nothing the author could do about it. The jobs are fast; that
+# is a better trade than a class of PR that silently cannot land.
 on:
   push:
     branches: [main]
-    paths-ignore:
-      - '**.md'
-      - 'docs/**'
-      - '.gitignore'
   pull_request:
     branches: [main]
-    paths-ignore:
-      - '**.md'
-      - 'docs/**'
-      - '.gitignore'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Docs
+
+# Builds the documentation site and deploys it to GitHub Pages at openblox.sh.
+#
+# A pull request builds but does not deploy, so a broken docs build is a red check
+# rather than a broken site. Only main deploys.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs
+  cancel-in-progress: false
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install
+        run: pip install -r requirements-docs.txt
+
+      # --strict turns warnings into errors, so a broken internal link or a page
+      # missing from the nav fails here instead of shipping.
+      - name: Build
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
+        with:
+          path: site
+
+  deploy:
+    name: Deploy
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

.gitignore

@@ -30,3 +30,6 @@ go.work.sum
 # Editor/IDE
 # .idea/
 # .vscode/
+
+# mkdocs build output
+site/

docs/CNAME

@@ -0,0 +1 @@
+openblox.sh

docs/contributing.md

@@ -0,0 +1,61 @@
+# Contributing
+
+The full guide lives in
+[CONTRIBUTING.md](https://github.com/blox-eng/openblox/blob/main/CONTRIBUTING.md). This
+is the short version.
+
+## Setup
+
+```sh
+git clone https://github.com/blox-eng/openblox
+cd openblox
+make            # vet + lint + test
+```
+
+Requires Go 1.25+ and [golangci-lint](https://golangci-lint.run) v2.
+
+**Install golangci-lint before you push.** `go vet` and `go test` catch less than CI
+does — the lint step adds revive, gosec, errorlint and bodyclose. Without it on your
+PATH, `make lint` fails open and you learn about a violation from a red PR instead of
+from your terminal.
+
+## Tests
+
+Unit tests run anywhere. Integration tests are behind the `integration` build tag and
+need a Docker host with gVisor registered as `runsc`:
+
+```sh
+make test-integration
+```
+
+CI currently *compiles* the integration tests but does not run them — a gap tracked in
+[#3](https://github.com/blox-eng/openblox/issues/3). A test that no longer builds is a
+test nobody runs, so keep them compiling even when you cannot execute them locally.
+
+## Working on the docs
+
+```sh
+pip install -r requirements-docs.txt
+mkdocs serve      # http://127.0.0.1:8000
+```
+
+The docs are markdown in `docs/`, so a change to behaviour and the change to its
+documentation belong in the same pull request.
+
+## Commits
+
+[Conventional Commits](https://www.conventionalcommits.org/) — CI enforces it, and
+releases are cut from it.
+
+```
+feat(sandbox): add per-command timeout clamping
+fix(docker): drop CAP_NET_RAW on create
+docs: explain the egress default
+```
+
+## Where to start
+
+Issues labelled [`good first issue`](https://github.com/blox-eng/openblox/labels/good%20first%20issue),
+or anything in the open backlog that looks like your kind of problem. If you are
+planning something substantial, open an issue first so the design can be discussed
+before you spend the effort.

docs/getting-started.md

@@ -0,0 +1,165 @@
+# Quick start
+
+## Prerequisites
+
+**A Docker daemon**, and **gVisor (`runsc`) registered with it**.
+
+openblox will not run a sandbox without gVisor. It does not fall back to `runc`, and
+that refusal is deliberate: falling back would silently run untrusted code on the host
+kernel while the API kept reporting success.
+
+Install gVisor per the [official instructions](https://gvisor.dev/docs/user_guide/install/),
+then register it:
+
+```json title="/etc/docker/daemon.json"
+{
+  "runtimes": {
+    "runsc": {
+      "path": "/usr/bin/runsc"
+    }
+  }
+}
+```
+
+```sh
+sudo systemctl reload docker
+docker info --format '{{json .Runtimes}}' | grep runsc   # confirm
+```
+
+If `runsc` is absent, `Create` returns an error wrapping `sandbox.ErrRuntimeUnavailable`
+— branch on that if you want to degrade gracefully rather than fail.
+
+## Install
+
+```sh
+go get github.com/blox-eng/openblox
+```
+
+## Run something
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/blox-eng/openblox/pkg/docker"
+    "github.com/blox-eng/openblox/pkg/sandbox"
+)
+
+func main() {
+    ctx := context.Background()
+
+    backend, err := docker.New()
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer backend.Close()
+
+    sb, err := backend.Create(ctx, "session-1",
+        sandbox.WithImage("ghcr.io/blox-eng/openblox-sandbox:latest"))
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer backend.Destroy(ctx, "session-1")
+
+    res, err := sb.Exec(ctx, sandbox.Command{
+        Argv: []string{"python3", "-c", "print(6 * 7)"},
+    })
+    if err != nil {
+        log.Fatal(err)
+    }
+    fmt.Println(string(res.Stdout)) // 42
+}
+```
+
+`Create` is keyed by name: calling it again with the same name returns the existing
+sandbox rather than a second one. That makes it safe to call per request without
+tracking what already exists.
+
+A non-zero `res.ExitCode` is the program failing, not an openblox error. `err` is
+reserved for openblox failing to run it at all.
+
+!!! note "Argv, not a shell string"
+    `Command.Argv` is passed directly to `exec`. Nothing in it is parsed as shell
+    syntax, so a caller cannot accidentally create an injection by interpolating
+    untrusted text into a command line.
+
+## Files
+
+```go
+err := sb.WriteFile(ctx, "/workspace/data.csv", 0o644, strings.NewReader("a,b\n1,2\n"))
+
+rc, err := sb.ReadFile(ctx, "/workspace/out.json")
+defer rc.Close()
+body, err := io.ReadAll(rc)
+```
+
+Both stream, so they are safe for large payloads. Paths are absolute inside the
+sandbox; `/workspace` is the working directory and is writable.
+
+## Background processes
+
+```go
+err := sb.StartProcess(ctx, "web", sandbox.Command{
+    Argv: []string{"python3", "-m", "http.server", "8080", "--bind", "127.0.0.1"},
+})
+```
+
+Idempotent: if something is already running under that name, it is left alone and no
+error is returned. Call it on every request rather than tracking state yourself.
+
+## Preview links
+
+A sandbox has **no network interface**, so a port inside it is not reachable by any
+ordinary route. openblox reaches it over the exec channel and fronts it with a signed,
+expiring URL.
+
+```go
+backend, err := docker.New(
+    docker.WithPreviews(signingKey, "https://example.com"), // key >= 32 random bytes
+)
+
+// Mount the handler where the signed URLs will resolve.
+http.Handle(preview.RoutePrefix+"/", backend.PreviewHandler())
+
+p, err := sb.Expose(ctx, 8080, 10*time.Minute)
+// p.URL + p.Token — send the token as an Authorization header, never a query param.
+```
+
+!!! warning "Revocation is best-effort; expiry is the guarantee"
+    Verification is a local HMAC check that consults no shared state, so `Revoke` only
+    holds in the process that recorded it. If you run several replicas, treat the TTL
+    as the real bound and keep it short.
+
+## Cleaning up
+
+```go
+removed, err := backend.Reap(ctx)   // destroys sandboxes past idle timeout or max age
+```
+
+Call it from a ticker. It is safe to run concurrently with everything else, and safe to
+run from several processes at once.
+
+## Defaults
+
+A sandbox created with no options gets:
+
+| | |
+|---|---|
+| Runtime | `runsc` (gVisor) |
+| Network | none |
+| User | `1000:1000` (non-root) |
+| Root filesystem | read-only |
+| CPUs | 2 |
+| Memory | 2 GiB |
+| Scratch disk | 1 GiB (tmpfs, drawn **from** the memory budget) |
+| Max processes | 256 |
+| Idle timeout | 15 minutes |
+| Max age | 2 hours |
+| Command timeout | 60s default, 10m ceiling |
+
+Scratch space is tmpfs, so it comes out of memory — keep disk at or below memory, and
+size both deliberately if your workload is heavy.