NOTE Blockwork is currently in active development and is not yet suitable for production environments. It is missing many features and does not yet fulfill its stated aims.

Getting Started

Recommended Pre-requisites for macOS

On macOS we recommend the following:

• XQuartz - to support X11 forwarding from applications running in the contained environment.
• Docker or Orbstack as the container runtime. Podman is supported but it exhibits poor filesystem performance.
• Python 3.11 installed through pyenv to protect your OS's default install from contamination.
• Poetry installed through Python's package manager i.e. python -m pip install poetry.

Recommended Pre-requisites for Linux

On Linux we recommend the following:

• Docker as the container runtime. Podman is supported but it exhibits poor filesystem performance (there are some notes to improve this in the troubleshooting section).
• Python 3.11 installed through pyenv to protect your OS's default install from contamination.
• Poetry installed through Python's package manager i.e. python -m pip install poetry.

Installing Blockwork

To install the bleeding edge version of Blockwork, use the following command:

$> python3 -m pip install git+https://github.com/blockwork-eda/blockwork

Setting up a Development Environment

Follow these steps to get a development environment:

# Clone the repository
$> git clone git@github.com:blockwork-eda/blockwork.git
$> cd blockwork
# Activate a poetry shell
$> poetry shell
# Install all dependencies (including those just for development)
$> poetry install --with=dev
# Bootstrap the example project
$> bw -C example bootstrap
# Run a test command
$> bw -C example exec -- echo "hi"

Troubleshooting

macOS

X11 Forwarding

• Ensure XQuartz is installed
• Tick "Allow connections from network clients" in XQuartz preferences
• Quit and re-open XQuartz
• Execute xhost +

NOTE The DISPLAY environment variable must be set to host.internal:0 for Docker/Orbstack or host.containers.internal:0 for Podman, this should be setup automatically by the framework.

Linux

Podman Socket

To start the user-space socket service execute:

$> systemctl --user status podman.socket

NOTE Do not use sudo as the service needs to run in user-space.

Slow Podman Performance

Ensure that you are using the overlay filesystem (fuse-overlayfs), as the default vfs is very slow!

$> sudo apt install -y fuse-overlayfs
$> podman system reset
$> podman info --debug | grep graphDriverName

If the graphDriverName is not reported as overlay, then you can try forcing it by editing ~/.config/containers/storage.conf to contain:

[storage]
driver = "overlay"

Then execute podman system reset again, and perform the same check for the graph driver.

After changing the filesystem driver, you will need to rebuild the foundation container as it is deleted by the reset command.