Welcome
Getting Started
Blockwork is compatible with Python version 3.8 through 3.11 and is developed using the Poetry packaging tool. To install Blockwork, check out the repository from GitHub and install it with Poetry:
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:
Setting up a Development Environment
Follow these steps to get a development environment:
# Clone the repository
$> git clone [email protected]: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:
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:
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.