ChimeraXWeb Backend Requirement

ChimeraXWeb requires a UCSF ChimeraX executable in the backend container or sidecar. It is not an optional enhancement: jobs fail when chimerax is missing.

Why This Is Required

ChimeraXWeb uses UCSF ChimeraX for structure superposition, RMSD, contacts, H-bonds, clashes, surface rendering, density-map fitting, and publication figure rendering. The browser preview uses NGL only for inspection before submitting a job.

Docker Build

The backend Dockerfiles install ChimeraX through backend_v2/scripts/install_chimerax_debian.sh when CHEMISTRYATLAS_INSTALL_CHIMERAX=true.

Because UCSF requires license acceptance before download, builds must pass:

CHIMERAX_LICENSE_ACCEPT=1

Example:

docker compose -f docker-compose.v2.yml -f docker-compose.roost.yml build \
  --build-arg CHIMERAX_LICENSE_ACCEPT=1 \
  --build-arg CHIMERAX_PLATFORM=ubuntu-24.04 \
  backend-v2

The default platform is ubuntu-24.04, which UCSF notes is based on Debian 13/Trixie. That matches the current ChemistryAtlas backend container family.

If the official metadata endpoint changes or you want to pin an installer, pass:

--build-arg CHIMERAX_DEB_URL="https://..."

Runtime Configuration

The app looks for ChimeraX in this order:

1. CHEMISTRYATLAS_CHIMERAX_BIN 2. CHIMERAX_BIN 3. chimerax on PATH 4. ChimeraX on PATH 5. /usr/bin/chimerax 6. /usr/local/bin/chimerax

Default Docker runtime sets:

CHEMISTRYATLAS_CHIMERAX_BIN=/usr/bin/chimerax

Verification

Inside the backend container:

command -v chimerax
chimerax --version

Through ChemistryAtlas:

curl -s -X POST http://127.0.0.1:5174/api/apps/chimerax-web/jobs \
  -H 'Content-Type: application/json' \
  --data '{"text":"workflow=publication_figure\nstyle=cartoon\ncolor=chain","parameters":{"chimerax_workflow":"publication_figure","chimerax_resolution":"1200x900"},"files":[]}'

If ChimeraX is missing, the job should fail with a message that starts:

ChimeraXWeb requires a UCSF ChimeraX executable.