bserver

A YAML-driven web server written in Go that generates complete HTML pages from structured YAML and Markdown definitions. Write YAML, get HTML — with virtual hosting, automatic HTTPS, and zero boilerplate.

Website: bserver.info

How It Works

bserver uses a pipeline of YAML definitions to build complete HTML pages. You only define main: — everything else is inherited:

html.yaml          ← starting point (provides <html lang="en">)
├── head.yaml      ← <head> with meta, title, styles
└── body.yaml      ← <body> wrapping:
    ├── header.yaml    ← navbar
    ├── main           ← YOUR CONTENT (from index.yaml)
    └── footer.yaml    ← footer text

Names resolve by searching upward through directories — your site's navlinks.yaml overrides the default, but inherited definitions like navbar.yaml are shared across all sites. Files are read on every request, so changes take effect immediately with no restart.

Features

YAML page generation — Define pages as structured YAML; bserver renders clean, indented HTML5
Markdown support — .md files render with full site chrome (navbar, header, footer, styles)
Format definitions — Reusable HTML templates via the ^name prefix, with variable substitution
Cascading name resolution — Definitions resolve upward through directories, child overrides parent
Proxy mode — Reverse-proxy a vhost to a backend server with a one-line index.yaml
Virtual hosting — Serve multiple domains from subdirectories, with a default/ fallback
Automatic HTTPS — Let's Encrypt certificates with self-signed fallback for local development
Bootstrap 5 — Pre-configured CSS and Font Awesome out of the box
Server-side scripting — Dynamic content via Python, JavaScript (Node.js), or PHP
Privilege dropping — Binds ports 80/443 as root, then drops to nobody
Merge definitions — Extend inherited definitions with the +name prefix
Style rendering — YAML-defined CSS with selector keys and property maps
Debug mode — Add ?debug to any URL (e.g., http://localhost/?debug) for HTML comment tracing
Hot reload — YAML/Markdown files are read per-request; no server restart needed
Access logging — Every request is logged with method, path, status, and duration
Graceful shutdown — Clean shutdown on SIGINT/SIGTERM for systemd compatibility

Quick Start

Requires Go 1.24 or later.

git clone https://github.com/stgnet/bserver.git
cd bserver
go build
./bserver

Then visit localhost (port 80 or as shown on startup) to see the built-in documentation site.

A minimal page needs just an index.yaml in www/example.com:

main:
  - h1: "Hello World"
  - p: "Welcome to my site."

This produces:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>bserver</title>
    ...
  </head>
  <body>
    <header>...</header>
    <main>
      <h1>Hello World</h1>
      <p>Welcome to my site.</p>
    </main>
    <footer>...</footer>
  </body>
</html>

Directory Structure

Go source files live in the project root. Web content lives in www/, mirroring the /var/www convention:

bserver/
├── *.go                     # Go source code
├── www/                     # Web content root (-base flag)
│   ├── default/             # Fallback for unmapped hosts
│   │   ├── index.yaml       # Home page
│   │   ├── header.yaml      # Site header
│   │   ├── footer.yaml      # Site footer
│   │   └── style.yaml       # Site styles
│   ├── example.com/         # Virtual host
│   │   ├── index.yaml
│   │   └── about.md
│   ├── html.yaml            # Base document structure (inherited)
│   ├── bootstrap5.yaml      # Bootstrap 5 CDN (inherited)
│   ├── navbar.yaml          # Navigation component (inherited)
│   └── cert-cache/          # TLS certificates (auto-created)
└── ...

The shared YAML definitions in www/ are readable and can be copied into any virtual host directory to customize behavior.

Installing as a Service

git clone https://github.com/stgnet/bserver.git
cd bserver
go build
sudo ./install-service.sh

Installs and starts bserver as a system service using systemd (Linux) or launchd (macOS). The service starts automatically and is enabled on boot.

To update and restart after pulling new changes:

git pull
go build
sudo ./install-service.sh restart

To uninstall:

sudo ./install-service.sh remove

Documentation

Getting Started — Installation, directory layout, first page
Content Definitions — How main: and named definitions work
Format Definitions — Custom HTML templates with ^name prefix
Built-in Components — Pre-defined YAML files (html, head, body, navbar, etc.)
Server-Side Scripts — Dynamic content via Python, JavaScript, PHP, Shell
Error Handling — Custom error pages
Server Features — Caching, security headers, rate limiting, TLS, and more
Proxy Mode — Reverse-proxy a vhost to a backend
Advanced Features — Virtual hosting, HTTPS, debug mode
Tips & Recipes — Common patterns and practical examples

License

Licensed under the Apache License 2.0. See LICENSE for details.