Docker - Linkspector

Linkspector provides an official Docker image that includes all dependencies, including Chromium for enhanced link checking with Puppeteer.

Quick Start

Clone the repository

git clone git@github.com:UmbrellaDocs/linkspector.git
cd linkspector

Build the Docker image

docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector .

The --build-arg LINKSPECTOR_PACKAGE= argument installs from the current directory rather than npm.

Run link check

Navigate to your project directory and run:

docker run --rm -it -v $PWD:/app \
  --name linkspector umbrelladocs/linkspector \
  bash -c 'linkspector check'

Building the Image

Build from Current Directory

Install the local version of Linkspector:

docker build --no-cache --pull --build-arg LINKSPECTOR_PACKAGE= -t umbrelladocs/linkspector .

Build Specific Version from npm

Install a specific version from npm:

docker build --build-arg LINKSPECTOR_VERSION=0.2.7 -t umbrelladocs/linkspector .

Build Latest from npm

Install the latest published version:

docker build -t umbrelladocs/linkspector .

Dockerfile Overview

The Linkspector Dockerfile includes:

FROM node:lts-bookworm-slim

# Chromium for Puppeteer (cross-platform ARM64/AMD64 support)
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium.wrapper

# Install dependencies
RUN apt-get update && apt-get install -y \
    bash ca-certificates chromium curl git upower

# Configure Chromium wrapper
RUN echo /usr/bin/chromium \
    --no-sandbox \
    --headless=new \
    --disable-gpu \
    --remote-debugging-port=0 \
    > /usr/bin/chromium.wrapper

# Install Linkspector
RUN npm install --global @umbrelladocs/linkspector

Why Chromium?

Linkspector uses Puppeteer with Chromium to check links in headless browser mode, which:

Reduces false positives from JavaScript-rendered sites
Handles complex redirects and client-side routing
Supports both ARM64 and AMD64 architectures

Running Linkspector

Basic Usage

Run with default configuration (.linkspector.yml):

docker run --rm -it -v $PWD:/app \
  --name linkspector umbrelladocs/linkspector \
  bash -c 'linkspector check'

Custom Configuration File

Specify a custom configuration file:

docker run --rm -it \
  -v $PWD:/app \
  -v $PWD/custom-config.yml:/path/to/custom-config.yml \
  --name linkspector umbrelladocs/linkspector \
  bash -c 'linkspector check -c /path/to/custom-config.yml'

JSON Output

Output results in RDJSON format:

docker run --rm -it -v $PWD:/app \
  --name linkspector umbrelladocs/linkspector \
  bash -c 'linkspector check -j'

Show Statistics

Display detailed link check statistics:

docker run --rm -it -v $PWD:/app \
  --name linkspector umbrelladocs/linkspector \
  bash -c 'linkspector check -s'

Volume Mounting

Mount Project Directory

The -v $PWD:/app flag mounts your current directory to /app in the container:

docker run --rm -it -v $PWD:/app umbrelladocs/linkspector bash -c 'linkspector check'

$PWD is a shell variable for the current directory. On Windows PowerShell, use ${PWD} instead.

Mount Specific Subdirectories

Check only specific documentation directories:

docker run --rm -it \
  -v $PWD/docs:/app/docs \
  -v $PWD/.linkspector.yml:/app/.linkspector.yml \
  umbrelladocs/linkspector \
  bash -c 'linkspector check'

Mount Multiple Configuration Files

docker run --rm -it \
  -v $PWD:/app \
  -v $PWD/configs:/configs \
  umbrelladocs/linkspector \
  bash -c 'linkspector check -c /configs/production.yml'

Docker Compose

Create a docker-compose.yml for repeatable link checking:

docker-compose.yml

version: '3.8'

services:
  linkspector:
    image: umbrelladocs/linkspector
    volumes:
      - ./:/app
    command: bash -c 'linkspector check'
    
  linkspector-json:
    image: umbrelladocs/linkspector
    volumes:
      - ./:/app
    command: bash -c 'linkspector check -j'
    
  linkspector-stats:
    image: umbrelladocs/linkspector
    volumes:
      - ./:/app
    command: bash -c 'linkspector check -s'

Run with:

# Run default check
docker-compose run --rm linkspector

# Get JSON output
docker-compose run --rm linkspector-json

# Show statistics
docker-compose run --rm linkspector-stats

CI/CD Integration

GitLab CI

.gitlab-ci.yml

check-links:
  stage: test
  image: umbrelladocs/linkspector
  script:
    - linkspector check
  only:
    - merge_requests
    - main

Jenkins

Jenkinsfile

pipeline {
  agent {
    docker {
      image 'umbrelladocs/linkspector'
    }
  }
  
  stages {
    stage('Check Links') {
      steps {
        sh 'linkspector check'
      }
    }
  }
}

CircleCI

.circleci/config.yml

version: 2.1

jobs:
  check-links:
    docker:
      - image: umbrelladocs/linkspector
    steps:
      - checkout
      - run:
          name: Check links
          command: linkspector check

workflows:
  test:
    jobs:
      - check-links

Advanced Usage

Interactive Shell

Open an interactive shell in the container:

docker run --rm -it -v $PWD:/app \
  umbrelladocs/linkspector \
  bash

Then run commands interactively:

linkspector --version
linkspector check -s
linkspector check -c custom-config.yml

Environment Variables

Pass environment variables for authentication:

docker run --rm -it \
  -v $PWD:/app \
  -e AUTH_TOKEN=your-secret-token \
  umbrelladocs/linkspector \
  bash -c 'linkspector check'

With .linkspector.yml:

dirs:
  - ./docs
httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${AUTH_TOKEN}

Custom Network

Run on a custom Docker network to access other containers:

# Create network
docker network create docs-network

# Run local documentation server
docker run -d --name docs-server --network docs-network nginx

# Check links on custom network
docker run --rm -it \
  -v $PWD:/app \
  --network docs-network \
  umbrelladocs/linkspector \
  bash -c 'linkspector check'

Save Results to File

Redirect output to a file on the host:

docker run --rm -it -v $PWD:/app \
  umbrelladocs/linkspector \
  bash -c 'linkspector check -j' > results.json

Or save within the container:

docker run --rm -it -v $PWD:/app \
  umbrelladocs/linkspector \
  bash -c 'linkspector check -j > /app/results.json'

Troubleshooting

Permission denied errors

If you encounter permission errors, ensure the mounted volume has correct permissions:

# Add user flag to run as current user
docker run --rm -it -v $PWD:/app \
  --user $(id -u):$(id -g) \
  umbrelladocs/linkspector \
  bash -c 'linkspector check'

Chromium crashes or fails to start

The Docker image is configured to run Chromium with:

--no-sandbox for containerized environments
--headless=new for improved performance
--remote-debugging-port=0 to avoid D-Bus issues

If issues persist, check Docker resource limits (RAM/CPU).

Cannot find configuration file

Ensure .linkspector.yml is in the mounted directory:

# Verify file exists
ls -la .linkspector.yml

# Explicitly mount configuration
docker run --rm -it \
  -v $PWD/.linkspector.yml:/app/.linkspector.yml \
  -v $PWD:/app \
  umbrelladocs/linkspector \
  bash -c 'linkspector check'

Network timeout errors

If external links timeout, increase Docker’s network timeout or add problematic domains to ignorePatterns in your configuration.

Container exits immediately

Add -it flags for interactive mode and proper TTY allocation:

docker run --rm -it -v $PWD:/app umbrelladocs/linkspector bash -c 'linkspector check'

Image Details

Base Image: node:lts-bookworm-slim
Included Tools: Node.js, npm, Chromium, Git, Bash
Working Directory: /app
Default User: node (non-root)
Architecture Support: AMD64, ARM64

Best Practices

Use .dockerignore

Create .dockerignore to exclude unnecessary files when building the image.

Pin Image Version

Use specific version tags in production instead of latest.

Multi-stage Builds

For custom images, use multi-stage builds to minimize image size.

Health Checks

Add health checks when running Linkspector as a service.

Next Steps

CI/CD Integration

Integrate Docker-based checks into CI/CD pipelines

GitHub Actions

Use the official GitHub Action instead of Docker

Get Started

Commands

Configuration

Guides

Reference

​Quick Start

​Building the Image

​Build from Current Directory

​Build Specific Version from npm

​Build Latest from npm

​Dockerfile Overview

​Why Chromium?

​Running Linkspector

​Basic Usage

​Custom Configuration File

​JSON Output

​Show Statistics

​Volume Mounting

​Mount Project Directory

​Mount Specific Subdirectories

​Mount Multiple Configuration Files

​Docker Compose

​CI/CD Integration

​GitLab CI

​Jenkins

​CircleCI

​Advanced Usage

​Interactive Shell

​Environment Variables

​Custom Network

​Save Results to File

​Troubleshooting

​Image Details

​Best Practices

Use .dockerignore

Pin Image Version

Multi-stage Builds

Health Checks

​Next Steps

CI/CD Integration

GitHub Actions

Build docs developers (and LLMs) love

Quick Start

Building the Image

Build from Current Directory

Build Specific Version from npm

Build Latest from npm

Dockerfile Overview

Why Chromium?

Running Linkspector

Basic Usage

Custom Configuration File

JSON Output

Show Statistics

Volume Mounting

Mount Project Directory

Mount Specific Subdirectories

Mount Multiple Configuration Files

Docker Compose

CI/CD Integration

GitLab CI

Jenkins

CircleCI

Advanced Usage

Interactive Shell

Environment Variables

Custom Network

Save Results to File

Troubleshooting

Image Details

Best Practices

Next Steps