whn0thacked/ooniprobe repository overview

⁠🐳 OONI Probe Docker

A high-quality, secure, and lightweight Docker image for the OONI Probe CLI. Designed to automatically run network measurements in the background.

This image is engineered with a focus on security (non-root), correct time handling, and minimal resource consumption.

⁠✨ Features

• 🔐 Security: Runs as non-root (UID/GID 1000), supports read_only filesystem.
• 🏗 Multi-arch: Supports amd64, arm64, arm/v7, arm/v6, 386. Perfect for Raspberry Pi and VPS.
• 🔄 Automation: Built-in runner for periodic test execution with resume support.
• 💾 Persistence: Persists configuration and run history across restarts.
• 🧠 Smart Execution: Supports both full test suites (unattended) and specific site lists (urls.txt).

⁠🏷 Image Tags

All tags are multi-arch manifests supporting: amd64, arm64, arm/v7, arm/v6, 386.

# Always up to date (recommended for most users):
image: whn0thacked/ooniprobe:latest

# Pinned to a specific version:
image: whn0thacked/ooniprobe:v3.24.0

⁠⚠️ Important Notice (Informed Consent)

Running OONI Probe can pose risks depending on your country and ISP. To run this container, you must explicitly confirm your consent to these risks via an environment variable.

Activation variable: informed_consent: "true"

⁠🚀 Quick Start (Docker Compose)

We strongly recommend using Docker Compose for easy management and security configuration.

⁠1. Prepare Directories

Since the container runs as user 1000, create the folders beforehand and set ownership to avoid permission errors (especially on Linux):

mkdir -p config data
sudo chown -R 1000:1000 config data

⁠2. Configuration File

Create a docker-compose.yml file:

services:
  ooniprobe:
    image: whn0thacked/ooniprobe:latest
    container_name: ooniprobe
    restart: unless-stopped

    environment:
      # MANDATORY: Consent confirmation
      informed_consent: "true"

      # Operational settings
      upload_results: "true"           # Upload reports to OONI
      sleep: "true"                    # Infinite loop (daemon mode)
      seconds_between_tests: "21600"   # Interval (sec) = 6 hours

    volumes:
      # Data and configs
      - ./config:/config
      - ./data:/data
      # Time sync with host (critical for correct logs)
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

    # Hardening (Security improvements)
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETUID
      - SETGID
    read_only: true
    tmpfs:
      - /tmp:rw,nosuid,nodev,noexec,size=16m

    # Resource limits (optional but recommended)
    deploy:
      resources:
        limits:
          cpus: "0.10"
          memory: 256M

    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

⁠3. Start

docker compose up -d

View logs: docker compose logs -f

⁠⚙️ Configuration

⁠Environment Variables

⁠Advanced / Entrypoint Variables

These control startup behavior in docker-entrypoint.sh:

⁠Volumes

⁠🧠 Runner Logic

The /app/probe.sh script manages the container behavior:

1. Validation: Checks informed consent, validates all env variables, verifies the binary exists and is executable.
2. Config Generation: Creates /config/config.json based on ENV variables.
3. Resume Support: Reads /data/last_run timestamp. If the interval hasn't elapsed since the last successful run (e.g., after a container restart), the runner waits for the remaining time instead of re-running immediately.
4. Mode Selection:
   • If /config/urls.txt exists ➔ runs checks for specific sites: ooniprobe run websites --input-file=/config/urls.txt
   • Else ➔ runs the full automatic test suite: ooniprobe run unattended
5. Loop: If sleep=true, sleeps for the configured interval and repeats from step 3. If sleep=false, the container exits after a single run.
6. Signal Handling: Gracefully handles SIGTERM/SIGINT — stops the running probe child process and cleans up the PID file.

⁠🛠 Building from Source

# Build for current architecture (latest ooniprobe version)
docker build -t ooniprobe:local .

# Build with a specific ooniprobe version
docker build --build-arg OONI_VERSION=v3.24.0 -t ooniprobe:v3.24.0 .

# Multi-arch build (requires docker buildx)
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6,linux/386 \
  -t whn0thacked/ooniprobe:latest \
  --push .

⁠Build Arguments

⁠🔍 Troubleshooting

⁠🔗 Useful Links

• CLI Source Code: github.com/ooni/probe-cli⁠
• OONI Documentation: ooni.org/support/ooni-probe-cli⁠
• Risk Information: ooni.org/about/risks⁠