https://github.com/icelk/kvarn
An extensible and efficient forward-thinking web server for the future.
https://github.com/icelk/kvarn
rust web-server
Last synced: about 1 year ago
JSON representation
An extensible and efficient forward-thinking web server for the future.
- Host: GitHub
- URL: https://github.com/icelk/kvarn
- Owner: Icelk
- License: apache-2.0
- Created: 2021-01-27T09:22:39.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-25T13:32:28.000Z (about 1 year ago)
- Last Synced: 2025-04-03T01:12:12.338Z (about 1 year ago)
- Topics: rust, web-server
- Language: Rust
- Homepage: https://kvarn.org
- Size: 11.1 MB
- Stars: 20
- Watchers: 2
- Forks: 2
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: roadmap.md
Awesome Lists containing this project
README
[](https://crates.io/crates/kvarn)
[](#contributing)
[](https://github.com/Icelk/kvarn/actions)
[](https://github.com/Icelk/kvarn/issues)
[](https://deps.rs/repo/github/Icelk/kvarn)
[](https://github.com/Icelk/kvarn/tree/main/)
# [Kvarn](https://kvarn.org/)
A forward-thinking fast web server designed to fit
your needs, efficiently.
Kvarn is a rusty,
open-source, extendable web application framework with
native async everywhere;
zero downtime; and
safe & fast defaults.
Kvarn is batteries-included (optional defaults) with support for
automatic HTTPS certificates, HTTP/3, io_uring everywhere,
reverse proxying, auto HTTP/2 push, in-memory caching (proper cache
invalidation), server communication provided by
a simple CLI, and easy website creation through Markdown and
Chute.
If you're looking for an **executable** to run your webserver with, see [Mölla](https://github.com/Icelk/moella).
Using Mölla, you can configure your host(s), add a search engine, authentication, and other parts of the
[Kvarn ecosystem](https://kvarn.org/ecosystem/). More info is available on [the website](https://kvarn.org/moella/).
See the [changelog](CHANGELOG.md) or visit [our website](https://kvarn.org/) for more info.
# Current state
A stable API is available and the crate is on [crates.io](https://crates.io/crates/kvarn).
You can view the latest documentation [online](https://doc.kvarn.org).
When using Mölla, you get access to all of Kvarn's extensions and most of it's features.
If you need to develop custom extension (like [those on icelk.dev](https://github.com/Icelk/icelk.dev/blob/main/server/src/main.rs#L44-L573))
you need to compile Kvarn yourself. Luckily,
[Mölla makes it easy to add custom extensions](https://github.com/Icelk/icelk.dev/blob/659df7f19b2ac22efbe4d20f0978c9f58964c76b/server/src/main.rs#L13-L21).
To use the latest and greatest you can add Kvarn as a git dependency, though the latest version is recommended:
```ini
[dependencies]
kvarn = { git = "https://github.com/Icelk/kvarn" }
```
## Dependencies
To increase security, build-times, reliability, and speed, I use dependencies sparingly.
The two heavy-hitters are `tokio` (async runtime for async networking, file access, and extensions) and `rustls` (for encryption, optional if you want to run a unsafe (often local) web server).
`brotli` and `flate2` are enabled by default to provide compression, but can be turned off.
`h2` provides optional (but _strongly preferred_) support for the HTTP/2 protocol.
See [kvarn.org](https://kvarn.org/cargo-features.) for more details.
## Pushing to production
Take a look at the [sample.service](https://github.com/Icelk/kvarn/blob/main/sample.service)
for how to configure systemd to use [kvarnctl](https://kvarn.org/ctl/) to manage Kvarn.
You can now use `systemctl --user reload kvarn` or similar to reload the server
if you've changed the config or recompiled (if that's your thing).
This ensures ([on Unix](https://kvarn.org/shutdown-handover.#handover)) **NO downtime**. Not even a millisecond.
# Installation
[Mölla](https://github.com/Icelk/moella#installation) is the recommended way to get started with Kvarn.
You can download it and other Kvarn tools (`kvarnctl` & `chute`)
for Linux and macOS at [the Releases page](https://github.com/Icelk/moella/releases).
For Kvarn chute downloads for Linux, go [here](https://github.com/Icelk/kvarn/actions/workflows/chute.yml)
and download the artefact from the topmost job.
`kvarnctl` is also available as [CI builds](https://github.com/Icelk/kvarn/actions/workflows/kvarnctl.yml).
# Documentation
Documentation of the main branch can be found at [doc.kvarn.org](https://doc.kvarn.org/).
To document with information on which cargo features enables the code,
set the environment variable `RUSTDOCFLAGS` to `--cfg docsrs`
(e.g. in Fish `set -x RUSTDOCFLAGS "--cfg docsrs"`)
and then run `cargo +nightly doc`.
# Changelog
See the [changelog](https://github.com/Icelk/kvarn/blob/main/CHANGELOG.md).
# Contributing
This library, and all other sub-projects in this repository,
are distributed under the Apache License 2.0.
So must all contributions also be.
All rights are reserved for images and logos unless explicitly stated otherwise.
You are free to use them if reasonable credit is given. I reserve the right to order you to remove any usage at will.