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?

../_images/intro-harp-start.excalidraw.png

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: