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,
cmakeandpkg-config. Theaws-lc-rscryptography 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
- KDL basics explains the syntax used above.
- TLS and certificates replaces
--dev-tlswith ACME or your own certificate. - Static sites, Reverse proxy and PHP and WordPress cover the common site types.
- Deployment shows how to run MiraServe as a service under an unprivileged user.
- CLI commands lists every command and flag.