# How to Run user‑scanner in a Docker Container: Complete Setup Guide

> Easily run user-scanner in a Docker container. This guide details building the image, installing dependencies, and setting up the entrypoint for seamless execution. Get started now.

- Repository: [Kaif/user-scanner](https://github.com/kaifcodec/user-scanner)
- Tags: how-to-guide
- Published: 2026-08-30

---

**To run user‑scanner in a Docker container, build an image from `python:3.12-slim`, install dependencies via [`requirements.txt`](https://github.com/kaifcodec/user-scanner/blob/main/requirements.txt), and execute `python -m user_scanner` as the container ENTRYPOINT with your desired CLI arguments.**

The `user-scanner` repository by kaifcodec is a pure‑Python OSINT aggregation framework that executes parallel username and email probes across hundreds of platforms. Its modular architecture—anchored by [`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py) and the orchestrator in [`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py)—requires only a standard Python runtime, making it ideal for containerized deployments without external binaries or system dependencies.

## Architecture Overview for Containerization

Before building the image, understand how the codebase initializes inside a container:

- **[`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py)** – The CLI entry point that parses arguments and boots the **core engine** ([`user_scanner/core/engine.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/engine.py)).
- **[`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py)** – Loads every scan module located under `user_scanner/user_scan/` and `user_scanner/email_scan/`, then dispatches concurrent requests using `httpx` and `curl_cffi` impersonation.
- **[`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py)** – Aggregates output from each module into a standardized result object.
- **[`pyproject.toml`](https://github.com/kaifcodec/user-scanner/blob/main/pyproject.toml)** and **[`requirements.txt`](https://github.com/kaifcodec/user-scanner/blob/main/requirements.txt)** – Declare the package metadata and frozen dependency tree needed for pip installation.

Because the tool is installable from PyPI as a library, the container simply needs to import the package and invoke the module.

## Creating the Dockerfile

Use a multi-stage build to minimize the final image size while ensuring compilation tools are available for dependencies like `curl_cffi`.

```dockerfile

# Dockerfile

FROM python:3.12-slim AS builder

# Install build-time dependencies

RUN apt-get update && apt-get install -y --no-install-recommends \
    gcc libc-dev && rm -rf /var/lib/apt/lists/*

# Copy metadata for pip installation

WORKDIR /app
COPY pyproject.toml .
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Runtime stage – minimal image

FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages

# Optional: expose a default working directory for scan outputs

VOLUME /output
ENTRYPOINT ["python", "-m", "user_scanner"]

```

This configuration installs the full dependency tree—including the orchestrator and all scan modules—into `/usr/local/lib/python3.12/site-packages`, making them available to the Python interpreter at runtime.

## Building the Docker Image

Execute the build command from the repository root:

```bash
docker build -t user-scanner .

```

The resulting image contains the complete `user-scanner` package, ready to execute scans without any host Python installation.

## Running Scans in Containers

Pass CLI flags directly after the image name; the ENTRYPOINT forwards them to [`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py).

### Basic Execution with Volume Mounting

Mount a host directory to `/output` to persist results generated by the **Result** abstraction:

```bash
docker run --rm -v "$(pwd)/output:/output" user-scanner example@example.com

```

### Email Scan with JSON Output

Specify an output path inside the mounted volume:

```bash
docker run --rm -v "$(pwd)/output:/output" user-scanner \
    -o /output/result.json example@example.com

```

### Interactive Terminal Session

For debugging or manual inspection:

```bash
docker run -it --rm user-scanner --help

```

## Advanced Configuration and Volume Management

When you run user‑scanner in a Docker container, consider these optimization patterns:

1. **Multi-stage builds** – The example above uses a builder stage with `gcc` and `libc-dev` to compile `curl_cffi`, then copies only the installed packages to the runtime stage. This eliminates build tools from the final image, reducing attack surface and image size.
2. **Output persistence** – The orchestrator writes data through the abstraction in [`user_scanner/core/result.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/result.py). Always mount a host volume to `/output` (or your custom path) when using the `-o` flag to prevent data loss when the container exits.
3. **CI/CD integration** – Because the container exits with the CLI’s return code, you can drop it into GitHub Actions or GitLab CI pipelines to automate OSINT workflows without installing Python on the runner.

## Summary

- **Base image** – Use `python:3.12-slim` to run user‑scanner in a Docker container with minimal overhead.
- **Entry point** – The `python -m user_scanner` command triggers [`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py), which initializes the core engine and orchestrator.
- **Dependency management** – Copy [`requirements.txt`](https://github.com/kaifcodec/user-scanner/blob/main/requirements.txt) (generated from [`pyproject.toml`](https://github.com/kaifcodec/user-scanner/blob/main/pyproject.toml)) during the build to install `httpx`, `curl_cffi`, and scan modules.
- **Data persistence** – Mount host directories to the container’s `/output` path to capture JSON or text reports generated by the Result abstraction.
- **Concurrency model** – The orchestrator spawns parallel workers from `user_scanner/user_scan/` and `user_scanner/email_scan/` modules without requiring privileged container access.

## Frequently Asked Questions

### Does user‑scanner require external binaries inside the container?

No. According to the kaifcodec/user-scanner source code, the tool relies entirely on Python libraries. The orchestrator in [`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py) uses `httpx` and `curl_cffi` for HTTP impersonation, eliminating the need for external cURL binaries or system packages in the final image.

### How do I pass custom CLI flags when running the container?

Append flags after the image name in your `docker run` command. The Dockerfile ENTRYPOINT array passes all arguments directly to [`user_scanner/__main__.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/__main__.py), which parses them via the CLI handler and passes them to the core engine.

### Where does the container load scan modules from?

The orchestrator dynamically imports Python modules located under `user_scanner/user_scan/` and `user_scanner/email_scan/` within the installed package directory (`/usr/local/lib/python3.12/site-packages`). These paths are hardcoded in [`user_scanner/core/orchestrator.py`](https://github.com/kaifcodec/user-scanner/blob/main/user_scanner/core/orchestrator.py) and execute automatically when the container starts.

### Can I deploy user‑scanner in Kubernetes?

Yes. The containerized design—using a standard Python ENTRYPOINT and no persistent state—makes it compatible with Kubernetes pods, Docker Compose stacks, and serverless container platforms. Simply mount a PersistentVolumeClaim to `/output` if you need to retain scan results.