Getting started / Quickstart

Quickstart

This page takes you from a source checkout to a running local HTTPS server in a few minutes. Then you write a small config for your own static site.

What you need

  • Rust 1.95 or newer (the workspace sets rust-version = "1.95").
  • A C compiler, cmake and pkg-config. The aws-lc-rs cryptography library needs them to build.
  • Git and curl.

MiraServe is in private testing and cannot be downloaded yet. The commands on this page show how it will work once the source is published; see availability.

Build

$ cd miraserve   # the source tree, once it is published
$ cargo build --release --locked --bin miraserve
$ ./target/release/miraserve version
miraserve 0.1.0-alpha.0
platform: aarch64-macos
defaults: TLS 1.3 only, X25519MLKEM768 PQC hybrid, H3/H2/H1, dual-stack IPv4+IPv6, cap-std, forbid(unsafe_code)

The rest of this page assumes the binary is on your PATH as miraserve. Either copy it there or replace miraserve with ./target/release/miraserve.

Validate the local example

The repository includes examples/dev-local.kdl. It listens only on the loopback address: HTTPS on port 8443 and plain HTTP on port 8080, which redirects to HTTPS. It serves the repository's docs folder as the site localhost:

server {
    listen "127.0.0.1:8443" protocols="h3,h2,h1"
    listen "127.0.0.1:8080" redirect-https=#true

    tls {
        min-version "1.3"
        pqc-hybrid #true
        key-isolation "in-process"
    }

    sandbox {
        landlock #true
        seccomp "strict"
    }
}

site "localhost" {
    security-headers "strict"
    root "docs"
}

Run miraserve check before every start or reload. It parses the file, rejects unknown settings, and warns about choices that weaken security. With --strict, any warning is an error:

$ miraserve check --strict --dev-tls examples/dev-local.kdl
OK: 'examples/dev-local.kdl' is valid (2 listener(s), 1 site(s), 0 route(s), TLS >= 1.3, PQC: X25519MLKEM768 enabled, 0 warning(s))

The example has no certificate configured. --dev-tls tells check that you will start the server with a temporary development certificate. Without that flag, check --strict stops on warning W015 (no certificate, ACME block or key daemon configured).

Run it

Start the server from the repository root, because root "docs" is a relative path:

$ miraserve run examples/dev-local.kdl --dev-tls

--dev-tls generates a self-signed ECDSA P-256 certificate in memory at startup. Browsers and curl will not trust it, which is why the commands below use -k. Never use --dev-tls in production.

On Linux the worker also turns on Landlock and seccomp. On macOS and Windows the log says these are Linux-only, and confinement to the document root through cap-std is still active.

Test it with curl

In a second terminal, request a file from the docs folder:

$ curl -skI https://localhost:8443/SPEC.md
HTTP/2 200
content-type: text/markdown; charset=utf-8
server: MiraServe
alt-svc: h3=":8443"; ma=86400
strict-transport-security: max-age=63072000; includeSubDomains
x-content-type-options: nosniff
referrer-policy: strict-origin-when-cross-origin
x-frame-options: DENY
cross-origin-opener-policy: same-origin
permissions-policy: geolocation=(), microphone=(), camera=()

The security headers come from security-headers "strict", which is also the default. The alt-svc header tells clients that HTTP/3 is available on the same port. Plain HTTP on port 8080 is redirected:

$ curl -sI http://localhost:8080/SPEC.md
HTTP/1.1 308 Permanent Redirect
location: https://localhost:8443/SPEC.md

A request for / returns 404, because docs has no index.html. Stop the server with Ctrl+C. It finishes open connections before it exits.

Serve your own static site

Make a folder with a page in it, and a config file next to it:

$ mkdir -p mysite/public
$ cd mysite
$ echo '<!doctype html><title>hi</title><p>Hello from MiraServe</p>' > public/index.html

Save this as mysite.kdl:

server {
    listen "127.0.0.1:8443" protocols="h3,h2,h1"
    listen "127.0.0.1:8080" redirect-https=#true
}

site "localhost" {
    preset "static-strict"
    root "/home/you/mysite/public"
}

Replace the root value with the full path of your public folder (run pwd in it to see it). Use an absolute path: newer builds reject a relative root.

The server block sets where MiraServe listens. Each site block matches a hostname. root is the folder it serves. The static-strict preset adds rules for static sites, such as refusing dotfiles like .env and .git. TLS 1.3 with post-quantum key exchange is on without any tls block.

Check it, including that the files it points to exist (--fs), then run it:

$ miraserve check --strict --dev-tls --fs mysite.kdl
OK: 'mysite.kdl' is valid (2 listener(s), 1 site(s), 0 route(s), TLS >= 1.3, PQC: X25519MLKEM768 enabled, 0 warning(s))
$ miraserve run mysite.kdl --dev-tls
$ curl -sk https://localhost:8443/
<!doctype html><title>hi</title><p>Hello from MiraServe</p>
$ curl -sk -o /dev/null -w '%{http_code}\n' https://localhost:8443/.env
404

Next steps