🚀 Buran Application Server

English · Русский · 中文

Buran is an application server written in Rust. It serves static files, routes requests, and runs your application code in a pool of embedded worker processes — the whole edge described by one declarative YAML config.

Its core is runtime-agnostic: language runtimes attach as separate pluggable modules instead of being compiled into the server. PHP is the first supported runtime, and more are planned.

If you have run nginx + FastCGI or NGINX Unit, the shape is familiar: networking and routing in one process, workers executing application code, no separate daemon wedged in between.

✨ Why Buran?

• 📦 One config, one edge – Router, static file handler and process supervisor live in a single native server binary; listeners, routes and applications are all described in one YAML file.
• 🔌 Pluggable runtimes – Runtimes attach as separate buran-<runtime> module binaries, so several versions run side by side (buran-php83, buran-php84, …) and new languages land without touching the core.
• ⚡ In-process execution – Worker processes run application code directly under the server's supervision — no FastCGI hop, no external process manager.
• 🛡️ Safe by default – Source files a runtime declares as executable are never served as static content, even if a rule would otherwise match them.
• 🧊 Static configuration – No live admin API. A config change means a reload/restart (or, in containers, a new container) — running state stays predictable and auditable.
• 🐳 Container-native – Runs correctly as PID 1 (reaps orphans, graceful SIGTERM/SIGINT shutdown). Official runtime images ship per version.

🧩 Supported languages

Runtimes plug in as separate modules, so the list grows without touching the core. What runs today:

Language	Image flavors	Status
	Debian, Alpine	✅ Supported

Several versions coexist side by side (buran-php83, buran-php84, …), so one image can serve applications pinned to different branches.

📋 Prerequisites

Pick your path:

• Docker – nothing but a container runtime. The official images bundle Buran, a PHP module and opcache.
• From source – Rust 1.88+. The PHP module additionally needs a libphp built with --enable-embed plus php-config and a C toolchain (the core server has no PHP dependency).

⚡ Quick Start

1. Write a config

Create buran.yaml — serve static files, fall back to a PHP front controller:

settings:
  modules: /usr/lib/buran/modules   # where the images install runtime modules

listeners:
  "*:8080":
    route: main

routes:
  main:
    - action:
        share: /www$uri            # try a real file first
        fallback:
          application: app         # anything else → PHP

applications:
  app:
    module: php85                  # → /usr/lib/buran/modules/buran-php85
    root: /www
    index: index.php
    processes: auto                 # one worker per CPU (the default; clamped by cgroup quota)

2. Run it 🐳

docker run --rm -p 8080:8080 \
  -v "$PWD/buran.yaml:/etc/buran/buran.yaml:ro" \
  -v "$PWD/public:/www:ro" \
  ghcr.io/buran-project/buran:php

Open http://localhost:8080. Done. 🎉

Not sure which module name to use? List what an image ships:

docker run --rm ghcr.io/buran-project/buran:php buran --modules

3. …or build from source 🦀

git clone https://github.com/buran-project/buran
cd buran

# Core server (no PHP toolchain needed):
cargo run -p buran -- --config examples/buran.yaml

4. Validate before you deploy ✅

buran --check-config --config /etc/buran/buran.yaml

This checks the schema and probes every runtime module for protocol compatibility, then exits non-zero on any problem — safe to gate a deploy on.

🧭 How it works

A request flows through four kinds of config objects:

   TCP :8080  ─►  listener  ─►  route  ─►  action  ─►  application
                (bind addr)   (match →    (share /     (runtime module
                              action)     return /      + worker pool)
                                          app / route)

• A listener binds a host:port and enters a route (or serves the built-in status endpoint).
• A route is an ordered list of match → action steps; the first match wins.
• An action serves static files (share), returns a code (return), jumps to another route (route), or dispatches to an application.
• An application binds a runtime module to a document root and a pool of worker processes.

📚 Documentation

Full docs live in docs/:

Document	What is inside
📖 Getting started	Run Buran with Docker or from source in minutes.
⚙️ Configuration reference	settings, listeners, access_log, env substitution, the status endpoint.
🧭 Routing	Routes, match conditions, actions, pattern syntax, rewrites.
📁 Static files	The share action, index files, MIME types, source-leak protection.
🧩 Applications & runtimes	Process pools, limits, the PHP module, how modules work (BWP).
🚢 Deployment	Docker images, distro packages, systemd, running as PID 1.
🖥️ CLI reference	Command-line flags, environment variables, signals.

🐳 Container images

Official images are published to the GitHub Container Registry:

Image	Contents
ghcr.io/buran-project/buran:php	Buran + latest PHP runtime module + opcache.
ghcr.io/buran-project/buran:php-alpine	Same, Alpine flavor.
ghcr.io/buran-project/buran:minimal	Buran only — static files & routing, no runtime module.

PHP branches 7.3 → 8.5 are built as a matrix, in Debian and Alpine flavors. Prebuilt distro packages (Alpine / Debian / RPM) are attached to every release. See Deployment for the full list and tags.

🛠️ Development

Buran is a Rust workspace:

Crate	Role
buran	Main process: CLI, config loading, module checks, supervision.
buran-router	HTTP/1.1, routing, rewrites, static files, dispatch, WebSocket.
buran-config	Config schema, validation, ${ENV} substitution.
buran-ipc	Buran Worker Protocol (BWP): framing & flat request encoding.
buran-worker	Worker-side SDK for building runtime modules.
buran-php	PHP runtime module: embedded libphp via a custom SAPI.
buran-echo	Reference event-loop module (concurrent BWP profile).

cargo build            # build the workspace
cargo test             # run the test suite
cargo run -p buran -- --config examples/buran.yaml

📄 License

Licensed under the Apache License 2.0.

---

Repository: github.com/buran-project/buran Container registry: ghcr.io/buran-project/buran

♥️ Issues and pull requests are welcome!