Skip to content

Building and running QCrBox components using the qcb command line tool#

Note

Make sure you have followed the steps in Setting up a development environment and you can run qcb --help successfully. As a general rule, qcb should be run from within the cloned QCrBox git repository (typically from the toplevel folder, although this is not required).

Listing available QCrBox components#

Let's check which components are available in QCrBox. 

$ qcb list components
qcrbox-nats
qcrbox-registry
qcrbox-nextflow
cod_check
crysalis-pro
crystal-explorer
dummy_cli
eval1x
mopro
olex2
qcrbox_quality
qcrboxtools
shelx
xharpy-gpaw
qcrbox-syslog
qcrbox-reverse-proxy

This list contains three "core" components (qcrbox-message-bus, qcrbox-registry, qcrbox-nextflow). You don't need to worry about these for using and interacting with QCrBox - they will be started automatically when you spin up the crystallographic application components.

The remaining components represent existing crystallographic software packages that are accessible from QCrBox. 

crystal-explorer
eval1x
olex2
qcrboxtools
shelx
xharpy-gpaw

Building components#

You can build the Docker image for a given component by running qcb build. For example, let's build the docker image for Olex2. Before we run the actual build, let's use the --dry-run flag to inspect what would happen. 

$ qcb build --dry-run olex2
Would build the following components (including dependencies): olex2

2025-07-30 15:28:05.639 | DEBUG    | pyqcrbox.cli.subcommands.build:task_build_docker_image:147 - Found 1 prebuild script(s) for 'olex2'
2025-07-30 15:28:05.643 | DEBUG    | pyqcrbox.cli.subcommands.build:task_build_docker_image:153 - No local build context found for service 'qcrbox-reverse-proxy', nothing to do.
2025-07-30 15:28:05.643 | DEBUG    | pyqcrbox.cli.subcommands.build:task_build_docker_image:153 - No local build context found for service 'qcrbox-syslog', nothing to do.
2025-07-30 15:28:05.663 | INFO     | pyqcrbox.cli.subcommands.build:<lambda>:83 - Would build Python package: pyqcrbox
2025-07-30 15:28:05.663 | INFO     | pyqcrbox.cli.subcommands.build:<lambda>:72 - Would pull/clone QCrBoxTools repo in /home/runner/work/QCrBox/QCrBox/.build/QCrBoxTools ...
2025-07-30 15:28:05.663 | INFO     | pyqcrbox.cli.subcommands.build:<lambda>:108 - Would build Python package: qcrboxtools
2025-07-30 15:28:05.663 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: base-ancestor
2025-07-30 15:28:05.664 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build base-ancestor'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.699 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560
2025-07-30 15:28:05.700 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: base-application
2025-07-30 15:28:05.700 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build base-application'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.733 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560
2025-07-30 15:28:05.733 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: base-novnc
2025-07-30 15:28:05.733 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build base-novnc'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.766 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560
2025-07-30 15:28:05.766 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: qcrbox-nats
2025-07-30 15:28:05.766 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build qcrbox-nats'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.799 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560
2025-07-30 15:28:05.800 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: qcrbox-registry
2025-07-30 15:28:05.800 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build qcrbox-registry'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.833 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560
2025-07-30 15:28:05.833 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: olex2
2025-07-30 15:28:05.833 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build olex2'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:05.866 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560

You will notice that the logging output mentions additional Python packages and docker images. These are prerequisites for running application containers such as Olex2. The qcb tool knows about their dependencies and builds them automatically. You can pass the --no-deps flag to only build Olex2 itself (this can speed up the build during development if you are certain that the dependencies are already up-to-date). 

$ qcb build --dry-run --no-deps olex2
Would build the following components (without dependencies): olex2

2025-07-30 15:28:07.203 | DEBUG    | pyqcrbox.cli.subcommands.build:task_build_docker_image:147 - Found 1 prebuild script(s) for 'olex2'
2025-07-30 15:28:07.223 | INFO     | pyqcrbox.cli.helpers.docker_project:build_single_docker_image:41 - Would build docker image: olex2
2025-07-30 15:28:07.223 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:64 - Would run docker compose command: '/usr/bin/docker compose --project-name=qcrbox --env-file=/home/runner/work/QCrBox/QCrBox/.env.dev --file=/home/runner/work/QCrBox/QCrBox/docker-compose.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.build.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.build.yml --file=/home/runner/work/QCrBox/QCrBox/docker-compose.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/cod_check/docker-compose.cod_check.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crysalis-pro/docker-compose.crysalis-pro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/crystal_explorer/docker-compose.crystal-explorer.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/dummy_cli/docker-compose.dummy_cli.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/eval1x/docker-compose.eval1x.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/mopro/docker-compose.mopro.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/olex2_linux/docker-compose.olex2_linux.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrbox_quality/docker-compose.qcrbox_quality.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/qcrboxtools/docker-compose.qcrboxtools.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/shelx/docker-compose.shelx.run.yml --file=/home/runner/work/QCrBox/QCrBox/services/applications/xharpy_gpaw/docker-compose.xharpy-gpaw.run.yml build olex2'
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/setuptools_scm/git.py:167: UserWarning: "/home/runner/work/QCrBox/QCrBox" is shallow and may cause errors
  warnings.warn(f'"{wd.path}" is shallow and may cause errors')
2025-07-30 15:28:07.259 | DEBUG    | pyqcrbox.cli.helpers.docker_project:run_docker_compose_command:68 - Current pyqcrbox version: 0.1.dev1+g5d52560

Ok, let's run the actual build process by removing the --dry-run flag. Note that the first time this command is executed it may take a few minutes to complete. 

$ qcb build olex2

Alternatively, if you want to build all available components, run: 

$ qcb build --all

Note

Certain components such as SHELX and Eval are disabled by default because they require password access for downloading executables or source code. These components will be skipped (even when using --all) unless the --enable flag is passed explicitly for each of these components that you'd like to enable. For example: 

$ qcb build --all --enable=shelx --enable=evl1x

Warning

Building components that are disabled by default may require you to set certain environment variables or download password-protected files manually and placing them in the correct location. We will provide much better support for this in the future as part of the qcb toolchain. For the time being, please get in touch if you would like to build these and need support.

Starting up containers#

You can start the Docker container for Olex2 by running: 

$ qcb up olex2
As above, if you want to start all (enabled) components, use the --all flag: 
$ qcb up --all

Warning

If you want start up containers after previously shutting them down (using qcb down as described below), you must currently manually delete the Docker volume where the QCrBox server stores information about available components:

# Step 1: Shut down all running containers
$ qcb down

# Step 2: Delete the Docker volume containing the QCrBox server database
$ docker volume rm qcrbox_qcrbox-registry-db

# Step 3: Now you can start up the components again and things should work as expected.
$ qcb up --all

This is of course less than ideal. The underlying issue is being addressed in a refactoring branch that will be merged very soon, at which point you will be able to shut down and spin up components ad libitum without manual intervention.

Shutting down containers#

Run the following command to shut down all running QCrBox containers: 

$ qcb down

Next steps#