Setting up a development environment#

Quick start#

Make sure you have the necessary prerequisites installed (see below for detailed instructions).

Docker / Docker Compose
WSL2 (Windows Subsystem for Linux 2) - only required for Windows

Then run the following command to download the setup script and install QCrBox.

$ bash <(curl -fsSL https://raw.githubusercontent.com/QCrBox/QCrBox/dev/scripts/qcrbox_setup.sh)

If you prefer to inspect the script before running it, you can download it first and then run it manually:

$ curl -fsSL https://raw.githubusercontent.com/QCrBox/QCrBox/dev/scripts/qcrbox_setup.sh > qcrbox_setup.sh
$ bash qcrbox_setup.sh

Info

If you are using Windows, make sure to run the above command in a WSL2 terminal, not in PowerShell or the Windows command prompt.

The setup script will give you the option to automatically install Devbox and Nix (if they are not already installed). Then it will clone the QCrBox repository and create an isolated development environment inside it. This development environment includes a virtual environment for the pyqcrbox Python package and all other dependencies needed to run and develop QCrBox. Once installation is complete, you can activate the development shell by running devbox shell.

QCrBox relies on Devbox to provide a consistent development environment. Internally, Devbox uses the Nix package manager to install packages into isolated environments.

The QCrBox setup script will give you the option to automatically install Devbox and Nix if they are not already installed.

Verify the installation#

Verify that we can now run the qcb command line tool, which is the main CLI interface for interacting with QCrBx from the command line.

$ qcb

 [33mUsage:[0m [1mqcb[0m [[1;36mOPTIONS[0m] [1;36mCOMMAND[0m [[1;36mARGS[0m]...                                         

 Command line interface for the Quantum Crystallography Toolbox.                

[2m╭─[0m[2m Options [0m[2m───────────────────────────────────────────────────────────────────[0m[2m─╮[0m
[2m│[0m [1;36m--verbose[0m  [1;32m-v[0m    Enables verbose mode (will print debugging messages about   [2m│[0m
[2m│[0m                  actions performed). [default: False]                        [2m│[0m
[2m│[0m [1;36m--help[0m     [1;32m-h[0m    Show this message and exit.                                 [2m│[0m
[2m╰──────────────────────────────────────────────────────────────────────────────╯[0m
[2m╭─[0m[2m Commands [0m[2m──────────────────────────────────────────────────────────────────[0m[2m─╮[0m
[2m│[0m [1;36mbuild     [0m[1;36m [0m Build QCrBox components.                                         [2m│[0m
[2m│[0m [1;36mup        [0m[1;36m [0m Start up QCrBox components.                                      [2m│[0m
[2m│[0m [1;36mdown      [0m[1;36m [0m Shut down QCrBox components.                                     [2m│[0m
[2m│[0m [1;36mlist      [0m[1;36m [0m List registered resources (applications, commands, etc.)         [2m│[0m
[2m│[0m [1;36minit      [0m[1;36m [0m Create boilerplate template for a new application.               [2m│[0m
[2m│[0m [1;36minvoke    [0m[1;36m [0m Invoke command with given arguments.                             [2m│[0m
[2m│[0m [1;36mstatus    [0m[1;36m [0m Retrieve the status of a QCrBox calculation                      [2m│[0m
[2m│[0m [1;36mdocs      [0m[1;36m [0m Build/serve the documentation.                                   [2m│[0m
[2m│[0m [1;36mdev       [0m[1;36m [0m Development-related commands.                                    [2m│[0m
[2m│[0m [1;36mvalidate  [0m[1;36m [0m Check application spec yaml file for errors.                     [2m│[0m
[2m│[0m [1;36mversion   [0m[1;36m [0m Print the qcrbox version.                                        [2m│[0m
[2m╰──────────────────────────────────────────────────────────────────────────────╯[0m

$ qcb version
0.1.dev1+g5d52560

$ 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

$ qcb list components --all
base-ancestor
base-application
base-novnc
base-wine
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

You can also test that the components build and run correctly by running a Devbox script,

$ devbox run test-api

Build a container to test the installation#

Try building a component by typing:

$ qcb build qcrboxtools
Building the following components (including dependencies): qcrboxtools

[32m2025-07-30 15:26:13.260[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.subcommands.build[0m:[36mtask_build_docker_image[0m:[36m153[0m - [34m[1mNo local build context found for service 'qcrbox-reverse-proxy', nothing to do.[0m
[32m2025-07-30 15:26:13.260[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.subcommands.build[0m:[36mtask_build_docker_image[0m:[36m153[0m - [34m[1mNo local build context found for service 'qcrbox-syslog', nothing to do.[0m
[32m2025-07-30 15:26:13.288[0m | [1mINFO    [0m | [36mpyqcrbox.cli.subcommands.build[0m:[36m<lambda>[0m:[36m83[0m - [1mBuilding Python package: pyqcrbox[0m
Building wheel...
/home/runner/.cache/uv/builds-v0/.tmpjkrUUZ/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')
Successfully built /home/runner/work/QCrBox/QCrBox/services/base_images/base_ancestor/pyqcrbox_dist/pyqcrbox-0.1.dev1+g5d52560-py3-none-any.whl
[32m2025-07-30 15:26:13.812[0m | [1mINFO    [0m | [36mpyqcrbox.cli.subcommands.build[0m:[36m<lambda>[0m:[36m72[0m - [1mPulling/cloning QCrBoxTools repo in /home/runner/work/QCrBox/QCrBox/.build/QCrBoxTools ...[0m
fatal: cannot change to '/home/runner/work/QCrBox/QCrBox/.build/QCrBoxTools': No such file or directory
Cloning into '/home/runner/work/QCrBox/QCrBox/.build/QCrBoxTools'...
[32m2025-07-30 15:26:14.205[0m | [1mINFO    [0m | [36mpyqcrbox.cli.subcommands.build[0m:[36m<lambda>[0m:[36m108[0m - [1mBuilding Python package: qcrboxtools[0m
Building wheel...
Successfully built /home/runner/work/QCrBox/QCrBox/services/base_images/base_ancestor/pyqcrbox_dist/qcrboxtools-0.0.5-py3-none-any.whl
[32m2025-07-30 15:26:14.464[0m | [1mINFO    [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mbuild_single_docker_image[0m:[36m41[0m - [1mBuilding docker image: base-ancestor[0m
[32m2025-07-30 15:26:14.465[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m64[0m - [34m[1mRunning 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'[0m
/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')
[32m2025-07-30 15:26:14.504[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m68[0m - [34m[1mCurrent pyqcrbox version: 0.1.dev1+g5d52560[0m
[32m2025-07-30 15:27:47.375[0m | [1mINFO    [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mbuild_single_docker_image[0m:[36m41[0m - [1mBuilding docker image: base-application[0m
[32m2025-07-30 15:27:47.376[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m64[0m - [34m[1mRunning 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'[0m
/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')
[32m2025-07-30 15:27:47.410[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m68[0m - [34m[1mCurrent pyqcrbox version: 0.1.dev1+g5d52560[0m
[32m2025-07-30 15:27:50.644[0m | [1mINFO    [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mbuild_single_docker_image[0m:[36m41[0m - [1mBuilding docker image: qcrbox-nats[0m
[32m2025-07-30 15:27:50.644[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m64[0m - [34m[1mRunning 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'[0m
/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')
[32m2025-07-30 15:27:50.678[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m68[0m - [34m[1mCurrent pyqcrbox version: 0.1.dev1+g5d52560[0m
[32m2025-07-30 15:27:53.031[0m | [1mINFO    [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mbuild_single_docker_image[0m:[36m41[0m - [1mBuilding docker image: qcrbox-registry[0m
[32m2025-07-30 15:27:53.031[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m64[0m - [34m[1mRunning 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'[0m
/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')
[32m2025-07-30 15:27:53.066[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m68[0m - [34m[1mCurrent pyqcrbox version: 0.1.dev1+g5d52560[0m
[32m2025-07-30 15:27:56.944[0m | [1mINFO    [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mbuild_single_docker_image[0m:[36m41[0m - [1mBuilding docker image: qcrboxtools[0m
[32m2025-07-30 15:27:56.944[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m64[0m - [34m[1mRunning 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 qcrboxtools'[0m
/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')
[32m2025-07-30 15:27:56.979[0m | [34m[1mDEBUG   [0m | [36mpyqcrbox.cli.helpers.docker_project[0m:[36mrun_docker_compose_command[0m:[36m68[0m - [34m[1mCurrent pyqcrbox version: 0.1.dev1+g5d52560[0m

Restart QCrBox#

In the event of disaster, it is possible to destroy the containers and restart QCrBox by using a Devbox script,

$ devbox run restart-qcrbox

Improving File Access Speed on Windows#

When using Docker on Windows with WSL2 (Windows Subsystem for Linux 2), file access in shared folders can be slow, which can cause problems for processes like data reduction. By default, the shared files are stored in <project_folder>/shared_files/ on your Windows drive. You should move the shared files to your WSL2 partition for faster access.

Steps#

Open WSL2:
Open a Windows command prompt
Type wsl and press Enter
Create a new folder in your WSL2 home directory using the mkdir command:
Important: Use lowercase letters only for the folder name!
Example: mkdir qcrbox_shared_files
Locate your Linux username:
Look at the command prompt; your username is before the @ symbol
Example: If you see john@DESKTOP-123:~$, your username is "john"
Update your QCrBox's .env.dev file in the QCrBox base directory:
Find the line starting with QCRBOX_SHARED_FILES_DIR_HOST_PATH

Replace it with one of these options:

For Windows 10:

QCRBOX_SHARED_FILES_DIR_HOST_PATH='\\wsl$\Ubuntu\home\<your_linux_username>\<folder_name>'

For Windows 11:

QCRBOX_SHARED_FILES_DIR_HOST_PATH='\\wsl.localhost\Ubuntu\home\<your_linux_username>\<folder_name>'

Example:

QCRBOX_SHARED_FILES_DIR_HOST_PATH='\\wsl$\Ubuntu\home\john\qcrbox_shared_files'

Make sure to use single quotes around the path

Prerequisites#

The following dependencies need to be installed manually.

Docker and Docker Compose

The easiest way to install Docker is to use the Docker Desktop (scroll down to find the box titled "Install Docker Desktop" and click on the link for your operating system).

If you don't care about a graphical user interface (for example, if you are working on a remote server), you can also manually install Docker Engine and Docker Compose.

Info

QCrBox has been tested with the version of Docker listed below, but other recent versions should also work. Please create an issue on GitHub if you experience any problems.

Note that QCrBox requires Docker Engine version 25.0 or later due to the use of --start-interval in container health checks.

$ docker version
Client:
 Version:           24.0.9
 API version:       1.43
 Go version:        go1.22.5
 Git commit:        v24.0.9
 Built:             Thu Jan  1 00:00:00 1970
 OS/Arch:           linux/amd64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          27.1.1
  API version:      1.46 (minimum version 1.24)
  Go version:       go1.21.12
  Git commit:       cc13f95
  Built:            Tue Jul 23 19:57:01 2024
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.7.19
  GitCommit:        2bf793ef6dc9a18e00cb12efb64355c2c9d5eb41
 runc:
  Version:          1.7.19
  GitCommit:        v1.1.13-0-g58aa920
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

$ docker compose version
Docker Compose version v2.21.0