> ## Documentation Index
> Fetch the complete documentation index at: https://p-bitm-2269ecee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Requirements

> Host, Docker, Python, networking, and authorization requirements for running P-BitM.

## Host

* Linux host recommended for production deployments.
* Python 3.9 or newer for the host CLI.
* Docker Engine 23.0 or newer with a running daemon. Use a currently supported
  release for production.
* Docker Buildx plugin, exposed as `docker buildx`.
* Docker Compose plugin, exposed as `docker compose`.
* Git and OpenSSL.
* Enough disk space for browser images, campaign artifacts, and exports.

The standalone `docker-compose` command and Docker's legacy image builder are
not supported. P-BitM uses BuildKit features and checks the complete Docker
toolchain before setup and startup.

Docker Desktop includes Buildx and Compose. Linux package names depend on how
Docker Engine was installed. Do not mix Ubuntu's Docker packages with Docker
CE packages from Docker's repository.

<Tabs>
  <Tab title="Ubuntu docker.io" icon="package">
    If the host uses Ubuntu's `docker.io` package, install Ubuntu's plugin
    packages:

    ```bash theme={"system"}
    sudo apt-get update
    sudo apt-get install docker-buildx docker-compose-v2
    ```

    These packages are distributed through Ubuntu's `universe` component, which
    is normally already enabled. If APT cannot locate them, check that component
    in the host's configured Ubuntu sources.
  </Tab>

  <Tab title="Docker CE" icon="container">
    If the host uses `docker-ce`, first configure
    [Docker's official Ubuntu repository](https://docs.docker.com/engine/install/ubuntu/),
    then install its plugin packages:

    ```bash theme={"system"}
    sudo apt-get update
    sudo apt-get install docker-buildx-plugin docker-compose-plugin
    ```

    For a new production host, the Docker CE installation documented by Docker is
    recommended. Whichever package family is selected, verify the resulting CLI:

    ```bash theme={"system"}
    docker version --format '{{.Server.Version}}'
    docker buildx version
    docker compose version
    ```
  </Tab>
</Tabs>

### Docker access and runtime ownership

Run the P-BitM CLI as the current user whenever possible. That user can have
any normal positive UID/GID. On rootful Linux, P-BitM automatically builds its
unprivileged `bitm` and `abc` container users with matching numeric IDs so they
can write the private bind-mounted storage:

```bash theme={"system"}
id -u
id -g
docker info
```

If Docker access requires elevation, add the dedicated P-BitM operator to the
`docker` group and start a new login session. Membership in that group grants
root-level control of the Docker host, so do not add untrusted users:

```bash theme={"system"}
sudo usermod -aG docker "$USER"
```

Running the CLI through `sudo` is supported when direct Docker access is not
available: the CLI uses `SUDO_UID` and `SUDO_GID` to preserve the original
user identity. A direct root launch also keeps every application container
non-root; it uses a non-root repository owner when available and otherwise
falls back to `1000:1000` inside the images. Running as the current user is
still simpler because it avoids root-owned generated files and unnecessary
host privilege.

The `storage/` tree must belong to the selected operator identity. P-BitM
creates its top-level directories with mode `0700` and safely repairs entries
left by an earlier root launch when root performs setup. It refuses to take
over data owned by an unrelated non-root user. Image labels record the chosen
IDs, allowing startup to rebuild incompatible local images automatically.

Docker Desktop uses its Linux VM to mediate bind mounts, so macOS keeps the
images' default `1000:1000` identity while host files remain owned by the macOS
user.

No BuildKit environment variables are required. A supported Engine uses
BuildKit by default, and P-BitM invokes Buildx explicitly for custom images.
`COMPOSE_DOCKER_CLI_BUILD` is unsupported by Compose v2.

The CLI supports `amd64` and `arm64` image selection. Actual browser streaming
support still depends on the host, container runtime, and selected image.

## Python dependencies

Install the root CLI dependencies from `requirements.txt`. A virtual
environment is recommended:

```bash theme={"system"}
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt
```

Running the backend source or its test suites directly outside Docker requires
Python 3.10 or newer. The application containers use their own supported
Python runtime, independently of the host CLI version.

## Network and DNS

The dashboard listens on `https://127.0.0.1:8443/` by default. Production
campaigns require:

* inbound TCP ports 80 and 443;
* DNS records resolving campaign hostnames to the deployment host;
* credentials for the DNS challenge provider configured in `config.yaml`.

Keep the administrative dashboard on loopback or behind a separately secured
administrative access layer.

## Authorization

Before deployment, define the approved targets, dates, operators, collection
scope, data retention, and emergency stop procedure in writing.