Introduction¶
We’ll guide you through the process of setting up a development environment, opening and understanding the architecture and concepts used (like dependency injection and event-driven hooks), navigating through the codebase, and finally writing code, including tests.
System requirements¶
You will need the following tools installed on your machine:
Git and GNU Make
A working Python 3.12 environment with the
poetry
package manager installed. We usually tend to use the latest stable version of Python.A working NodeJS (lts/iron) environment with the
pnpm
package manager installed.A working Docker + Docker Compose environment.
Source code¶
Once the system requirements are met, you can download the source code, using git clone
:
git clone git@github.com:msqd/harp.git
Install the project’s dependencies (isolated):
cd harp
make install-dev
This will install the dependencies in a separate virtual environment (managed by poetry) and set up the development environment.
Note
Depending on your system, you may get a warning about playwright not finding the system dependencies it needs. This is only required if you want to run the browser based tests, and can be safely ignored. On a linux system, you can install the missing dependencies with:
(cd harp_apps/dashboard/frontend; pnpm exec playwright install-deps)
Running¶
You can start your first HARP development server based on your local working copy.
Here, we’ll run one using one of the built-in examples (but the same applies to any configuration, of course):
poetry run harp start --example sqlite
Open your browser at http://localhost:4080 to have a look at the HARP dashboard.
Using harp start
(or poetry run harp start
to let poetry manage the env, our preference) will spawn
a bunch of processes, managed by honcho, with some free cherries.
The default processes are:
harp server
: the main server, python based, which will listen for incoming requests on different ports. By default, it listens to the 4080 port for the dashboard. Wrapped using watchfiles to restart on code changes.the dashboard’s devserver (vite based): listens to a high random unprivileged port by default, and the main server will forward requests tto this port. Meaning that harp dashboard’s goes through the http proxy. Kinda meta, right?

You can read more about the various harp
commands in the Command Line Reference.
Interfaces¶
The main developer interface is a Makefile
, containing the most common tasks you’ll need to run. Get a list by
running:
make help
For anything requiring a valid environment to run, you can use the poetry run harp
command, which will run the HARP
CLI within the poetry-managed virtualenvironment.
Next steps¶
Congratulations, you’re ready to start writing HARP code! Before that, you may want to have a glance at the following topics: