Installation¶

This section provides instructions on how to install OCDocker.

Prerequisites¶

Make sure you have the following prerequisites installed:

Python (>=3.11)
Conda (Miniconda/Anaconda) with mamba
pip (inside the conda environment)
NVIDIA driver/runtime compatible with CUDA 12.8 (required to run Gnina CUDA builds)

Quickstart (minimal, SQLite)¶

If you want the fastest path without setting up PostgreSQL/MySQL, use SQLite (local file DB) as the backend:

Ensure the system dependencies are installed (see System dependencies).
Create/activate a conda env with Python 3.11 (prefer mamba) and install OCDocker with pip.

Enable SQLite when running commands:

export OCDOCKER_DB_BACKEND=sqlite
ocdocker doctor

SQLite is recommended for quick experiments and development. PostgreSQL is the default backend, and MySQL is optional for alternative server-based workflows.

System dependencies¶

Before installing OCDocker, you must install the following system packages on Ubuntu/Debian systems:

sudo apt-get install openbabel libopenbabel-dev swig cmake g++

These packages are required for building and using OpenBabel Python bindings, which are essential for OCDocker’s molecular processing capabilities.

Gnina (CUDA 12.8)¶

OCDocker expects the Gnina CUDA 12.8 build. To run this binary reliably, ensure:

NVIDIA driver is compatible with CUDA 12.8
cuDNN 9 runtime is available on the system

Step-by-step installation:

mkdir -p gnina
wget -O gnina/gnina.1.3.2.cuda12.8 \
  https://github.com/gnina/gnina/releases/download/v1.3.2/gnina.1.3.2.cuda12.8
chmod +x gnina/gnina.1.3.2.cuda12.8
sudo install -m 0755 gnina/gnina.1.3.2.cuda12.8 /usr/bin/gnina

Verify:

gnina --version

Note: install.sh already installs this Gnina CUDA 12.8 binary automatically.

Installing OCDocker¶

To install OCDocker, follow these steps:

Ensure the system dependencies are installed (see System dependencies).

Install mamba (if not already installed):

conda install -n base -c conda-forge mamba

Create and activate a conda environment:

mamba create -n ocdocker python=3.11 -y
conda activate ocdocker

Install OCDocker with pip (choose one option):

Option A: install from PyPI (recommended for users):
```
pip install ocdocker
```
pip install ocdocker installs the minimal core (CLI bootstrap, config I/O, logging, and serialization helpers). Feature-specific dependencies are optional extras — see Optional dependencies for the full cheat sheet, per-extra package lists, and command mapping.

Quick install commands:
```
pip install ocdocker                      # minimal core
pip install "ocdocker[docking]"           # vs / pipeline
pip install "ocdocker[db]"                # --store-db
pip install "ocdocker[ml]"                # OCScore ML
pip install "ocdocker[analysis]"          # plots / statistics
pip install "ocdocker[all]"               # all runtime stacks
pip install -e ".[all,dev]"               # typical developer setup
```
Typical combinations (details in Optional dependencies):
- Single-engine docking: ocdocker[docking]
- Multi-engine pipeline with dendrogram output: ocdocker[docking,analysis]
- OCScore replication: ocdocker[ml] (often ocdocker[all] for full parity)
Option B: install from source (recommended for development):
```
git clone https://github.com/Arturossi/OCDocker.git
cd OCDocker
./scripts/vendor_oddt.sh

# Minimal core
pip install -e .

# Typical developer install
pip install -e ".[all,dev]"
```
vendor_oddt.sh must run before pip install -e – it vendors our ODDT fork, which OCDocker’s packaging picks up as a local oddt/ directory instead of a normal dependency. Skipping it leaves import oddt resolving to whatever (if any) vanilla oddt package happens to already be on your PYTHONPATH, which does not have the fixes this project relies on.

Optional: build the Sphinx documentation¶

If you want to build docs locally in the same ocdocker conda environment:

Option A (conda/mamba):

mamba install -n ocdocker -c conda-forge sphinx sphinx-argparse furo sphinx-rtd-theme myst-parser
make -C docs html

Option B (pip extras):

pip install -e ".[full]"
make -C docs html