Skip to content
nurburg.dev

nurburg.dev — The Platform for Backend System Design Experiments

nurburg.dev is a platform for designing, deploying, and benchmarking backend systems. Define your infrastructure as code in a git repository, run it in an isolated environment, and get performance scores you can compare across experiments.

Experiments, components, and tasks

Section titled “Experiments, components, and tasks”

You define an experiment in a git repository. nurburg.dev deploys your services and databases in an isolated environment, runs your load tests and API tests against them, and produces scores.

An experiment consists of:

  • Components — long-running infrastructure: your service and supporting databases
  • Tasks — short-lived jobs that run after components are ready: load tests, API tests, data seeders, and failure injection
  • Scores — named metrics evaluated at the end to measure success
  • Telemetry — time-series metrics collected during the run and displayed in the experiment report

Run your first experiment

Section titled “Run your first experiment”

  1. Create a GitHub repository for your experiment. By convention, name it experiment-my-project for explorations or challenge-my-project for challenge submissions.

  2. Create the .nurburgdev/ directory at the root of your repo. This is where your experiment configuration lives.

  3. Write experiment.toml to declare your infrastructure and tests:

    .nurburgdev/experiment.toml
    description = "My first experiment"
    

    [[service]]
    name = "app"
    runtime = "nodejs"
    port = 3000
    healthCheckUrl = "/health"
    cpuCores = 0.5
    memoryMB = 256
    instances = 1
    env = {DATABASE_URL = "postgres://user:pass@db:5432/mydb"}
    

    [[postgres]]
    name = "db"
    cpuCores = 0.5
    memoryMB = 512
    storageGB = 10
    dbName = "mydb"
    user = "user"
    password = "pass"
    

    [[traffic]]
    file = ".nurburgdev/traffic.js"
    

    [[score]]
    name = "ERR_RATE"
    taskName = "traffic"
    threshold = 5.0

  4. Create a Procfile in your service’s source directory (defaults to the repo root). It tells nurburg.dev how to build and start your service:

    build: go build -o ./app .
    web: ./app

    build runs once before web and must exit with code 0. For runtimes with no compile step, omit it:

    web: node server.js
    build: mvn package -q
    web: java -jar target/app.jar

  5. Write a k6 load test at .nurburgdev/traffic.js. The HOST environment variable is automatically set to your service’s base URL:

    import http from "k6/http";
    import { sleep } from "k6";
    

    export const options = {
      vus: 50,
      duration: "60s",
    };
    

    export default function () {
      http.get(`${__ENV.HOST}/api/items`);
      sleep(0.5);
    }

  6. Push to GitHub and go to nurburg.dev/new to connect your repository and run your first experiment.

Repository structure

Section titled “Repository structure”
  • Directoryyour-repo/
    • Directory.nurburgdev/
      • experiment.toml
      • traffic.js
      • apitest.tavern.yaml (optional API tests)
      • README.md (experiment writeup shown on nurburg.dev)
    • Procfile (or inside service subdirectory)
    • Directorysrc/
      • …

The .nurburgdev/README.md is your experiment’s writeup on nurburg.dev. It uses standard Markdown with a YAML frontmatter block:

---
title: "My Experiment"
author: "Anunay Biswas"
authorLink: "https://github.com/anunaybiswas"
authorTitle: "Software Engineer"
summary: "One-sentence description shown in listings"
publishedOn: 2024-06-01
tags: [postgres, scalability]
intent: "experiment"
draft: false
---


Your writeup goes here...

Next steps

Section titled “Next steps”

Components

See all supported services, databases, caches, and messaging systems in the Components reference.