Skip to content

Development

Marco Quinten edited this page Jul 24, 2023 · 4 revisions

This page contains extensive documentation on how to work on hdrop itself.

Stack

Let's talk about the development stack first.

Backend

The backend is written in Rust. We recommend using the latest stable toolchain.
You will find instructions on installing Rust on https://rust-lang.org.

Frontend

The backend is written in TypeScript and uses Next.js.
We use the yarn package manager (https://yarnpkg.com/getting-started/install).

Docker

We heavily use Docker (https://www.docker.com) for testing everything locally.

Prerequisites

  • PostgresQL development binaries and headers

Linux

On Debian, Ubuntu: sudo apt install libpq-dev.
On Fedora, RHEL: sudo dnf install libpq-devel.

macOS

Install using brew: brew install libpq.

If you get errors, you might have to also run brew link --force libpq.
If you still get errors, run cargo clean and cargo build again.

Running hdrop locally

There are multiple ways of running hdrop locally:

Using Docker

This is super easy to set up and the recommended way of running hdrop for development.

Our docker compose file configures everything you need:

Service Port Description
Backend 8080 Rust backend
Frontend 3000 Next.js frontend
Postgres 15 5432 Postgres database
LocalStack 4566, 4567 Local Amazon S3 emulation
Prometheus 9090 Prometheus metrics server

To make development easier, the frontend is built with live-reload enabled.

You can spin up the full stack by running:
docker compose up --build

ℹ️ In our experience the live-reload freezes from time to time.
If this happens, just restart the stack: docker compose down && docker compose up --build

Using the start_api script

We provide a hybrid solution to run the server locally and everything else in Docker. This enables faster debugging in cases where you have to restart the server many times and observe changes quickly.

  1. Make sure that the docker compose stack is down
    • You can run docker compose down to do this
  2. Run ./start_api.sh

The script does the following:

  • Start the Docker compose stack (docker compose up --build --wait -d)
  • Trap the EXIT and SIGINT signals to spin the Docker stack down on Ctrl+C
  • Run migrations against the Postgres database running in Docker
  • Build the Rust server in release mode
  • Configure environment variables that are compatible with the Docker stack
  • Run the Rust server in release mode

Running on bare-metal

We don't recommend this, since it's not at all easy to set up.

Essential, you'll have to do the following:

  • Set up a Postgres instance (we recommend Postgres 15 or newer)
  • Set up a Prometheus server and configure it to ingest from hdrop
    • This is optional, but needed when testing metrics
  • Set up a LocalStack instance (which you'll most likely do in Docker anyway)
  • Export the relevant env variables specific to your setup
  • Run the server and the frontend

We don't really do this ourselves, but it should work just fine.