Vicarian is a reverse proxy server with built-in ACME support. It is currently targeted at self-hosting and SOHO installations; in particular it supports provisioning TLS certificates behind-the-firewall via ACME DNS-01 and the zone-update library.
This software should be consider pre-alpha; the feature-set is MVP and is still in active development. It should not be considered production-ready and no warranty is expressed or implied.
Only Linux is currently supported (x86_64 and Arm64). Testing for other platforms is welcome.
- Multiple HTTP and HTTPS backend: Route traffic to multiple backend services based on URL contexts
- Basic path rewriting: This may work with some simple apps that don't support contexts natively, but is likely to fail with more complex apps that have hardcoded paths.
- Dynamic Certificate Loading: Externally provided TLS certificates are monitored and reloaded on update.
- ACME Support: Automatic certificate issuance and renewal via ACME protocol; both HTTP and DNS types are supported.
- Multiple DNS Providers: Multiple DNS providers for ACME are supported via the zone-update project. See that project for a list of supported providers.
- Virtual hosts
- Automated functional/integration testing
- Access logs
The following may be implemented at some point depending on interest and resources.
- Static files.
- TLS-ALPN-01 ACME support.
- Prometheus stats.
- Load-balancing, round-robin, etc.
- Advanced connection tuning
Tarballs are available on the Github release page. These contain binaries, documentation, example configuration files, and an example systemd configuration.
cargo install vicarianThe binary will be available at ~/.crates/bin/vicarian.
An example systemd service in provided in systemd/vicarian.service. The
systemd service sets the CAP_NET_BIND_SERVICE flag which allows binding to
ports 80/443 without root.
Vicarian currently uses the corn configuration
language. The default configuration file is located at
/etc/vicarian/vicarian.corn, but can be changed with the --config flag.
The full configuration structure is documented in
CONFIGURATION.md, and additional examples are available in
the examples directory, but a basic working configuration with HTTP-based
Let's Encrypt TLS would look like:
{
listen = {
addr = "[::]" // Default; this covers IPv4 & IPv6
insecure_port = 80 // Disabled by default, this will redirect to HTTPS
tls_port = 443 // Default
}
vhosts = [
{
hostname = "example.com"
tls = {
acme = {
contact = "admin@example.com"
challenge.type = "http-01"
}
}
backends = [
{
context = "/"
url = "http://localhost:8080"
}
{
context = "/app2"
url = "https://localhost:8443"
trust = true
}
]
}
]
}
At this point the most useful contributions would be to add additional DNS provider APIs to the zone-update project. However contributions to this project are welcome.
LLM and related 'AI' technologies can be useful for software development, but best-practices on their usage are still evolving. For this reason this project will not accept runtime code generated by AI. Generation of draft documentation and test code is acceptable, but should be reviewed by the submitter before raising a PR. After all, if you can't be bothered to review it why should anybody else?
- Vicarian binds to ports 80 and 443 by default, requiring appropriate permissions
- The systemd service uses
CAP_NET_BIND_SERVICEto bind to privileged ports without full root privileges - Private keys are stored in PEM format and should be properly secured
- When using ACME with DNS-01 challenges, ensure DNS provider API credentials are stored securely
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.