Projects · Infrastructure

A reproducible research environment

I want each project to run the same way on my laptop and on a server, so I can reproduce the results that go into a paper. This page explains how I set that up.

The problem it solves

A common problem in empirical work is that a result depends on the package versions installed on one laptop. A year later, the figure won't regenerate, and even the person who made it can't reconstruct how it was produced.

I give each project its own environment with fixed dependency versions. A single command rebuilds every figure from the raw data, without relying on anything important left on the host machine. So reproducing the work is part of how the project is set up.

Architecture

I run the whole environment in containers. Each service has its definition in a single file and runs separately from the others. I use the same definitions in development and production, so the setup works the same way in both.

Containerized services

I use Docker Compose to define the web server, language runtime, and database. Each runs as a separate service with a fixed version. One file defines the whole stack, which I start with a single up command.

Reproducible pipelines

Each analysis repo has one entry point that rebuilds all outputs from source. It takes the raw data through to the figures without manual steps or hidden state.

Self-hosted

I run everything on a small cluster of my own machines, which I administer myself. I've set up TLS and database backups, and I control the deployments. There's no hosting platform between me and the hardware.

Automation

I use scripts to regenerate widgets and rerun pipelines, so I don't have to repeat that work by hand.

I organize every project the same way. This site's stack is one example. Its three services have fixed versions and communicate only with each other over a private network. The application is built from a local image, and I keep all secrets out of the repo.

compose.yml · this site's stack

services:
  db:                     # MariaDB, pinned
    image: mariadb:11
    env_file: .env        # secrets, never in git
    volumes: [db_data:/var/lib/mysql]
    networks: [internal]  # private to the stack

  php:                    # built from a local image
    build: { context: ., dockerfile: Dockerfile.php }
    networks: [internal]
    healthcheck:          # auto-restart if it stalls
      test: ["CMD", "php", "-r", "echo 'ok';"]

  web:                    # nginx, the only exposed service
    image: nginx:alpine
    depends_on: [php]
    networks: [internal]

volumes:  { db_data: {} } # survives a full rebuild
networks: { internal: { driver: bridge } }

What runs on it

This environment runs both the site and the research codebases behind my papers. Automation keeps them in sync by regenerating chart widgets and rerunning pipelines when the data changes. So I maintain the research and the platform together as one system.

Why it matters

I built this setup for my research, so I can rebuild a result when needed. A reviewer can also run the code and check how I produced a figure.

The research codebases page describes the pipelines this infrastructure runs. For the publishing platform, see the page about this site.