### Install and Manage Systemd Timers

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Installs the headless-shell, enables user services, and starts systemd timers for daily builds and maintenance. Use 'systemctl list-timers --user' to check timer status and 'journalctl --user -u headless-shell.service -f' to view build logs.

```bash
# Install units and enable the daily build + maintenance timers
./install.sh

# After install, enable and start the timers manually:
sudo loginctl enable-linger $USER      # allow user services to run without a session

systemctl enable --now --user headless-shell.timer        # daily build at 02:05
systemctl enable --now --user podman-image-prune.timer    # periodic image prune
systemctl enable --now --user git-gc-chromium-src.timer   # weekly git gc (Fri 23:15)
systemctl enable --now --user git-gc-depot-tools.timer    # weekly git gc for depot_tools

# Check timer status
systemctl list-timers --user

# View build logs
journalctl --user -u headless-shell.service -f
```

--------------------------------

### Install systemd User Units

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Copies systemd service and timer files to the user's systemd directory and reloads the daemon. This enables scheduled daily builds.

--------------------------------

### Connect chromedp Go Library to Headless Shell

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Demonstrates how to connect the chromedp Go library to a running headless-shell container using a WebSocket connection. Ensure the container is started with the CDP port exposed.

```go
package main

import (
    "context"
    "log"

    "github.com/chromedp/chromedp"
)

func main() {
    // Connect to headless-shell running in the container
    // podman run -d -p 9222:9222 --rm docker.io/chromedp/headless-shell
    allocCtx, cancel := chromedp.NewRemoteAllocator(
        context.Background(),
        "ws://localhost:9222",
    )
    defer cancel()

    ctx, cancel := chromedp.NewContext(allocCtx)
    defer cancel()

    var title string
    if err := chromedp.Run(ctx,
        chromedp.Navigate("https://example.com"),
        chromedp.Title(&title),
    );
     err != nil {
        log.Fatal(err)
    }

    log.Printf("Page title: %s", title)
    // Output: Page title: Example Domain
}
```

--------------------------------

### Running the Headless Shell Container

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Start the headless-shell container, exposing the Chrome DevTools Protocol (CDP) port. Consider increasing shared memory or using security options for specific use cases.

```sh
# Basic run — exposes CDP on localhost:9222
podman run -d -p 9222:9222 --rm --name headless-shell \
  docker.io/chromedp/headless-shell
```

```sh
# If headless-shell crashes with BUS_ADRERR, increase shared memory
podman run -d -p 9222:9222 --rm --name headless-shell \
  --shm-size 2G \
  docker.io/chromedp/headless-shell
```

```sh
# Run as an unprivileged user with a Chrome-specific seccomp profile
# Download profile first:
# curl -O https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json
podman run -d -p 9222:9222 \
  --user nobody \
  --security-opt seccomp=chrome.json \
  --entrypoint '/headless-shell/headless-shell' \
  docker.io/chromedp/headless-shell \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222 \
  --disable-gpu \
  --enable-unsafe-swiftshader \
  --headless
```

--------------------------------

### Smoke-test a Built Image

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Tests a built headless shell image by starting it, waiting for the CDP endpoint, and verifying the Chrome version. Essential for ensuring build integrity.

```shell
./test.sh
```

```shell
./test.sh -v 123.0.6312.86 -t arm64 -p 5001
```

--------------------------------

### Dockerfile for Headless Shell Container Image

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Defines a minimal Debian-based Docker image that includes headless-shell binaries and necessary shared libraries. It exposes CDP ports and sets the entrypoint script. The example includes commands for manual image building.

```dockerfile
FROM docker.io/library/debian:trixie-slim
ARG VERSION

# Install only the shared libraries headless-shell actually needs
RUN apt-get update -y \
  && apt-get install --no-install-recommends -y \
     libnspr4 libnss3 libexpat1 libfontconfig1 libuuid1 socat \
  && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

# Copy pre-built binaries (VERSION = e.g. "123.0.6312.86-amd64")
COPY out/$VERSION/headless-shell/ /headless-shell/
COPY run.sh /headless-shell/

EXPOSE 9222   # external CDP port (socat forwarder)
EXPOSE 9223   # internal headless-shell CDP port

ENV LANG en-US.UTF-8
ENV PATH /headless-shell:$PATH

ENTRYPOINT [ "/headless-shell/run.sh" ]

# Build the image manually (normally done by build-image.sh via buildah):
# mkdir -p out/123.0.6312.86-amd64
# tar -C out/123.0.6312.86-amd64 -jxf out/headless-shell-123.0.6312.86-amd64.tar.bz2
# docker build --build-arg VERSION=123.0.6312.86-amd64 -t headless-shell:local .
```

--------------------------------

### Container Entrypoint Script (`run.sh`)

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Reference for the container's entrypoint script, which sets up TCP forwarding and launches headless-shell with software rendering. Additional Chrome flags can be passed at container startup.

```sh
# run.sh (executed automatically by the container — shown here for reference)
#!/bin/bash
set -ex

# Forward external port 9222 to internal headless-shell port 9223
exec socat TCP4-LISTEN:9222,fork TCP4:127.0.0.1:9223 &

# Launch headless-shell with software GL rendering (no GPU required)
exec /headless-shell/headless-shell \
  --no-sandbox \
  --use-gl=angle \
  --use-angle=swiftshader \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9223 \
  "$@"
```

```sh
# Pass additional Chrome flags at container startup:
podman run -d -p 9222:9222 --rm docker.io/chromedp/headless-shell \
  --disable-web-security \
  --allow-running-insecure-content
```

--------------------------------

### Manage Zombie Processes with --init

Source: https://github.com/chromedp/docker-headless-shell/blob/main/README.md

Use the --init argument with podman run to automatically reap zombie processes when using the headless-shell image.

```sh
$ podman run -d -p <PORT>:<PORT> --name <your-program> --init <your-image>
```

--------------------------------

### Full Pipeline Orchestrator for Daily CI Builds

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Drives the entire build process, from querying versions to building images and pushing to the registry. Use this as the primary entry point for automated daily builds.

```shell
./build.sh -p
```

```shell
./build.sh -c stable -j 14 -u -p
```

```shell
./build.sh -c stable -c beta -t amd64
```

--------------------------------

### Compiling Headless Shell from Source (`build-headless-shell.sh`)

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Command to build the headless-shell binary from the Chromium source tree. Specify output directories, channel, parallel jobs, and target architecture.

```sh
# Build stable channel, amd64 only, using 16 parallel jobs
./build-headless-shell.sh \
  -o /mnt/out \
  -s /media/src \
  -c stable \
  -j 16 \
  -t amd64
```

--------------------------------

### Manage Zombie Processes with ENTRYPOINT

Source: https://github.com/chromedp/docker-headless-shell/blob/main/README.md

For Docker versions older than 1.13.0, configure your Dockerfile's ENTRYPOINT to use dumb-init or tini to manage zombie processes.

```Dockerfile
FROM docker.io/chromedp/headless-shell:latest
...
# Install dumb-init or tini
RUN apt install dumb-init
# or RUN apt install tini
...
ENTRYPOINT ["dumb-init", "--"]
# or ENTRYPOINT ["tini", "--"]
CMD ["/path/to/your/program"]
```

--------------------------------

### Build and Push Multi-arch OCI Images

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Builds OCI images for specified architectures from archives, tags them, and optionally pushes them to a registry. Useful for creating distributable Docker images.

```shell
./build-image.sh \
  -o ./out \
  -v 123.0.6312.86 \
  -t amd64 \
  -t arm64 \
  -g stable \
  -g latest \
  -p
```

```shell
./build-image.sh \
  -o ./out \
  -v 123.0.6312.86 \
  -t amd64
```

--------------------------------

### Handling Zombie Processes in Headless Shell

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Manage zombie child processes when running headless-shell as a base image using the `--init` flag or a dedicated init process like `dumb-init`.

```sh
# Recommended: use podman/docker --init flag (Docker >= 1.13)
podman run -d -p 9222:9222 --name my-app --init my-image
```

```dockerfile
# For Docker < 1.13: use dumb-init inside a derived Dockerfile
FROM docker.io/chromedp/headless-shell:latest

RUN apt-get update && apt-get install -y dumb-init && rm -rf /var/lib/apt/lists/*

ENTRYPOINT ["dumb-init", "--"]
CMD ["/path/to/your/program"]
```

--------------------------------

### Run Headless Shell Container

Source: https://github.com/chromedp/docker-headless-shell/blob/main/README.md

Basic command to run the headless-shell container. If experiencing crashes, increase the shm-size. For unprivileged execution, specify user, security options, and entrypoint with debugging flags.

```sh
# run
$ podman run -d -p 9222:9222 --rm --name headless-shell docker.io/chromedp/headless-shell
```

```sh
# if headless-shell is crashing with a BUS_ADRERR error, pass a larger shm-size:
$ podman run -d -p 9222:9222 --rm --name headless-shell --shm-size 2G docker.io/chromedp/headless-shell
```

```sh
# run as unprivileged user
# get seccomp profile from https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json
$ podman run -d -p 9222:9222 --user nobody --security-opt seccomp=chrome.json --entrypoint '/headless-shell/headless-shell' docker.io/chromedp/headless-shell --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --disable-gpu --enable-unsafe-swiftshader --headless
```

--------------------------------

### Pull Headless Shell Image Tags

Source: https://github.com/chromedp/docker-headless-shell/blob/main/README.md

Use these commands to pull the latest stable, a specific version, beta, or dev channel of the headless-shell image using Podman.

```sh
# pull latest stable
$ podman pull docker.io/chromedp/headless-shell:latest
```

```sh
# pull specific version
$ podman pull docker.io/chromedp/headless-shell:123.0.6312.86
```

```sh
# pull beta
$ podman pull docker.io/chromedp/headless-shell:beta
```

```sh
# pull dev
$ podman pull docker.io/chromedp/headless-shell:dev
```

--------------------------------

### Remove Stale Artifacts and Images

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Cleans up old build archives, extracted directories, and dangling images based on specified criteria. Use to manage disk space and remove outdated build artifacts.

```shell
./cleanup.sh -c stable
```

```shell
./cleanup.sh \
  -c stable \
  -c beta \
  -c dev \
  -v 123.0.6312.86 \
  -v 124.0.6367.29 \
  -m 30              # mtime threshold in days (default: 90)
```

--------------------------------

### Verifying Headless Shell CDP Endpoint

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Check if the headless-shell container is responding on the CDP /json/version endpoint.

```sh
# Verify the container is responding on the CDP /json/version endpoint
curl http://localhost:9222/json/version
# Expected output:
# {
#   "Browser": "Chrome/123.0.6312.86",
#   "Protocol-Version": "1.3",
#   ...
# }
```

--------------------------------

### Pulling Docker Headless Shell Images

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Pull pre-built headless-shell images from Docker Hub using floating channel or pinned version tags.

```sh
# Pull the latest stable build (equivalent to 'stable')
podman pull docker.io/chromedp/headless-shell:latest
```

```sh
# Pull a specific Chrome version
podman pull docker.io/chromedp/headless-shell:123.0.6312.86
```

```sh
# Pull the beta channel build
podman pull docker.io/chromedp/headless-shell:beta
```

```sh
# Pull the dev channel build
podman pull docker.io/chromedp/headless-shell:dev
```

--------------------------------

### Build Specific Chrome Version with Source Update

Source: https://context7.com/chromedp/docker-headless-shell/llms.txt

Builds a specific Chrome version for multiple architectures, forcing a source update. Use when you need a precise version for amd64 and arm64, ensuring the latest source code is used.

```shell
./build-headless-shell.sh \
  -o /mnt/out \
  -s /media/src \
  -c stable \
  -v 123.0.6312.86 \
  -t amd64 \
  -t arm64 \
  -u \
  -j 18 \
  -a 5          # max 5 build attempts before giving up
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.