jailrun is a powerful tool designed to create fully isolated environments on your machine utilizing the capabilities of FreeBSD. By booting a FreeBSD virtual machine, jailrun enables the creation of lightweight, isolated environments known as jails, each possessing its own filesystem, network configuration, and process space. Users simply define their applications, and jailrun automates the management of these isolated environments.

Key Features

What is a Jail?

A jail represents a self-contained environment operating within FreeBSD. It ensures strict separation; nothing within a jail can access aspects outside its boundaries, preserving the integrity of the host system. This technology is a native feature of FreeBSD, known for being quick to set up, cost-effective, and easy to recreate or dismantle. jrun simplifies the setup of FreeBSD jails on macOS and Linux systems, bringing a robust isolation solution to a wider audience.

Quick Setup and Usage

Initiating the system is straightforward. The command:

jrun start

downloads the FreeBSD image and launches the VM. After the setup, connect with:

jrun ssh

Configuring Your First Jail

To create a new jail, users can utilize configuration files written in UCL, a user-friendly format resembling JSON. For instance, the following configuration sets up a simple HTTP server jail:

jail "simple-server" {
  forward {
    http { host = 7777; jail = 8080; }
  }
  mount {
    src { host = "."; jail = "/srv/project"; }
  }
  exec {
    server {
      cmd = "python3.13 -m http.server 8080";
      dir = "/srv/project";
    }
  }
}

Executing jrun up web.ucl brings this configuration to life, creating a robust, isolated environment ready for testing and development.

Advanced Stack Configuration

Building more complex applications involving multiple services is seamless with jailrun. A sample configuration for a FastAPI application interconnected with a PostgreSQL database might look like this:

jail "fastapi-314" {
  base { type = "jail"; name = "hypha-python-314"; }
  depends ["hypha-postgres"]
  setup {
    fastapi { type = "ansible"; file = "playbooks/fastapi-314.yml"; }
  }
}

This versatility allows developers to create modular applications with ease, using jails to isolate and connect various components.

Integration with Playbooks

For convenience, jailrun supports shared playbooks via the jailrun-hub, allowing users to deploy standard configurations for common services such as Redis or Nginx. This feature enhances productivity and ensures configurations can be reused across multiple projects.

Testing and Debugging

jailrun also supports integration with testing frameworks. For example, a pytest fixture can spin up a PostgreSQL jail during tests, enabling developers to run tests against real services isolated from the host environment:

@pytest.fixture
def postgres() -> Generator[PostgresJail]:
    with PostgresJail(Path("examples/postgres.ucl"), jail="hypha-postgres") as pg:
        yield pg

Robust Monitoring and Resource Management

Developers can manage the resources allocated to each jail, including setup processes that can be monitored and automatically restarted on failure, ensuring high availability and reliability of services.

In conclusion, jailrun offers a feature-rich solution for developers looking to leverage the isolated environments provided by FreeBSD jails, facilitating seamless application development and deployment on both macOS and Linux.