Vicarian

A modern reverse proxy with built-in ACME support for automatic TLS certificate management

Secure, automated reverse proxy for self-hosted applications

Reverse Proxy

Route traffic to multiple backend services based on URL contexts. Perfect for microservices and complex application setups.

Dynamic Certificates

Automatically provision and renew TLS certificates using ACME protocol with both HTTP-01 and DNS-01 challenge types.

DNS Integration

Support for multiple DNS providers via the zone-update library. Configure automatic certificate management behind firewalls.

About Vicarian

Vicarian is a reverse proxy server designed for self-hosting and small office/home office installations. It's targeted at users who want to run their own web services with automatic SSL/TLS certificates.

This software is currently in pre-alpha stage with a minimal viable product (MVP) feature set. It should not be considered production-ready, but is actively being developed.

// Basic configuration example (corn format)
{
    listen = {
        addr = "[::]"  // Default; this covers IPv4 & IPv6
        tls_port = 443 // Default
        // Non-ACME traffic will redirect to TLS.
        // his is also implied by the ACME config below.
        insecure_port = 80
    }

    vhosts = [
        {
            hostname = "www.example.com"

            tls = {
                acme = {
                    contact = "admin@example.com"
                    // This implicitly enables port 80 above
                    challenge.type = "http-01"
                    profile = "shortlived"  // Default: tlsserver
                }
            }

            backends = [
                {
                    // A service that does not allow a custom root/context,
                    // so we must place at root.
                    context = "/"
                    url = "http://localhost:8443"
                    // This service enforces TLS with a self-signed cert, so
                    // we need to disable certificate verification.
                    trust = true
                }
                {
                    // A better behaved service that allows a custom root.
                    context = "/copyparty"
                    url = "http://localhost:9090"
                }
            ]
        }
    ]
}

Configuration Examples

Certificate Files

Using pre-generated certificate files:


// Certificate Files (corn format)
tls = {
  port = 443
  config = {
    files = {
      keyfile = "/path/to/private.key"
      certfile = "/path/to/certificate.crt"
      reload = true
    }
  }
}

ACME with DNS

Automatic certificate management via DNS-01 challenge:


// ACME with DNS (corn format)
tls = {
  port = 443
  config = {
    acme = {
      acme_provider = "letsencrypt"
      contact = "admin@your-domain.com"
      challenge_type = {
        type = "dns-01"
        dns_provider = {
          name = "porkbun"
          key = $env_PORKBUN_KEY
          secret = $env_PORKBUN_SECRET
        }
      }
    }
  }
}

Installation

Building from Source

git clone https://github.com/tarka/vicarian.git
cd vicarian
cargo build --release

The binary will be available at target/release/vicarian

Systemd Service

An example systemd service is provided in systemd/vicarian.service. The systemd service sets the CAP_NET_BIND_SERVICE flag which allows binding to ports 80/443 without root.