{"id":35790441,"url":"https://github.com/tarka/vicarian","last_synced_at":"2026-03-11T05:06:13.969Z","repository":{"id":317314540,"uuid":"1066850177","full_name":"tarka/vicarian","owner":"tarka","description":"Vicarian is a TLS-first reverse proxy with built-in ACME support. ","archived":false,"fork":false,"pushed_at":"2026-01-12T07:32:12.000Z","size":442,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-12T17:39:19.104Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://vicarian.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T03:41:42.000Z","updated_at":"2026-01-12T07:31:56.000Z","dependencies_parsed_at":"2025-09-30T07:06:48.011Z","dependency_job_id":"a18e723f-2ac1-4f2d-bab8-1d26ff588a64","html_url":"https://github.com/tarka/vicarian","commit_stats":null,"previous_names":["tarka/proxeny","tarka/vicarian"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/tarka/vicarian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarka%2Fvicarian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarka%2Fvicarian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarka%2Fvicarian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarka%2Fvicarian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarka","download_url":"https://codeload.github.com/tarka/vicarian/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarka%2Fvicarian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28387596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T13:42:20.960Z","status":"ssl_error","status_checked_at":"2026-01-13T13:42:03.276Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-07T08:11:31.072Z","updated_at":"2026-03-07T06:15:59.163Z","avatar_url":"https://github.com/tarka.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vicarian\n\n[Vicarian](https://vicarian.org/) is a TLS-first reverse proxy server with\nbuilt-in ACME support. It is currently targeted at self-hosting and SOHO\ninstallations; in particular it supports provisioning TLS certificates\nbehind-the-firewall via ACME DNS-01 and the\n[zone-update](https://github.com/tarka/zone-update/) library.\n\nVicarian aims to have sensible defaults without additional configuration.\n\n## Project Status\n\n[![Crates.io](https://img.shields.io/crates/v/vicarian)](https://crates.io/crates/vicarian)\n[![GitHub CI](https://github.com/tarka/vicarian/actions/workflows/tests.yml/badge.svg)](https://github.com/tarka/vicarian/actions)\n[![License](https://img.shields.io/crates/l/vicarian)](https://github.com/tarka/vicarian/blob/master/README.md#License)\n\nThis software should be consider pre-alpha; the feature-set is\n[MVP](https://en.wikipedia.org/wiki/Minimum_viable_product) and is still in\nactive development. It should not be considered production-ready and no warranty\nis expressed or implied. It is very-much a work-in-progress and virtually every\npart of it subject to change without notice.\n\nOnly Linux is currently supported (x86_64 and Arm64). Testing for other\nplatforms is welcome.\n\n## Features\n\n### Current features\n\n- **TLS-first**: Port-80/HTTP can be enabled, but will always redirect to the\n  configured TLS server. The exception to this is when the HTTP-01 ACME is\n  enabled; Vicarian will serve any challenge responses directly.\n- **Native ACME Support**: Vicarian has first-class support for\n  ACME/LetsEncrypt, including DNS-01. LetEncrypt [certificate\n  profiles](https://letsencrypt.org/docs/profiles/) are supported; `tlsserver`\n  is the default.\n- **Multiple DNS Providers**: Multiple DNS providers are supported for DNS-01\n  via the [zone-update](https://github.com/tarka/zone-update/)\n  sibling-project. See that project for a list of supported\n  providers. (Contributions of provider support are very welcome.)\n- **Dynamic Certificate Loading**: Where TLS certificates are maintained\n  externally Vicarian will dynamically reload certificates when they are\n  updated.\n- **Simple backend routing**: Traffic can be routed to multiple backend services\n  based on URL paths.\n- **Basic path rewriting**: This may work with some simple apps that don't\n  support contexts natively, but is likely to fail with more complex apps that\n  have hardcoded paths.\n- **Virtual hosts**: Hosting of multiple domains and domain aliases is\n  supported, along with certificate generation for host aliases.\n- **Separated secrets**: ACME DNS requires DNS-provider secrets to be\n  configured. These can be placed in a separate secure file using systemd\n  [EnvironmentFile](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#EnvironmentFile=)\n  and [corn](https://cornlang.dev) environment injection (see\n  [vicarian-dns01.corn](examples/vicarian-dns01.corn) for an example).\n- **Wildcards**: Wildcard ACME certificate generation.\n\n### To-dos\n\n- Access \u0026 error logs\n- [Happy Eyeballs](https://en.wikipedia.org/wiki/Happy_Eyeballs) support\n- Static file support. Pingora itself doesn't support static-files. There are\n  3rd-party crates that support this but they appear unmaintained at the moment\n  and will need to be evaluated. If you wish to serve a static website one\n  workaround is to use `static-web-server` to create a static backend:\n\n      static-web-server \\\n          --host 127.0.0.1 --port 8080 \\\n          --security-headers true \\\n          --log-level info \\\n          --root .\n\n  This is how [vicarian.org](https://vicarian.org/) and\n  [haltcondition.net](https://haltcondition.net/) are served currently.\n- Docker images.\n\n### Possible Future Features\n\nThe following may be implemented at some point depending on interest and\nresources.\n\n- TLS-ALPN-01 ACME support.\n- Other ACME providers (e.g. ZeroSSL)\n- Prometheus stats.\n- HTTP3/Quic support.\n- [h2c](https://httpwg.org/specs/rfc7540.html#versioning) backend support\n  (avoids a lot of proxy security corner-cases, but there's not much support in\n  backend server software).\n- Basic [12-factor](https://12factor.net/config)-style\n  configuration. This should be relatively easy due to\n  [corn's](https://cornlang.dev/) support for environment injection; however\n  there is a [known issue](https://github.com/corn-config/corn/issues/49)\n  limiting this currently.\n\n### Probably-not features\n\nVicarian is very opinionated and tries to do the sensible thing by\ndefault. Ideally if a particular header or setting was usually required by, say,\n`nginx` then it should be the default. e.g. `X-Forwarded-For` and\n[HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Strict-Transport-Security)\nare always set. Consequently there are no plans to add a large number of\nfeatures and settings.\n\nOther notable non-features:\n\n- Load-balancing, round-robin, complex rewrite rules, etc.\n- Advanced connection tuning\n\n## Installation\n\n### Release Binaries\n\nTarballs are available on the [Github release page](https://github.com/tarka/vicarian/releases). \nThese contain binaries, documentation, example configuration files, and an example\nsystemd configuration:\n\n```\n├── bin\n│   └── vicarian\n├── CONFIGURATION.md\n├── etc\n│   ├── systemd\n│   │   └── system\n│   │       └── vicarian.service\n│   └── vicarian\n│       ├── examples\n│       │   ├── vicarian-dns01.corn\n│       │   ├── vicarian-http01.corn\n│       │   └── vicarian-tls-files.corn\n│       ├── secrets\n│       └── vicarian.corn\n├── LICENSE\n└── README.md\n```\n\n\n### Install from crates.io\n\n```bash\ncargo install vicarian\n```\n\nThe binary will be available at\n`~/.crates/bin/vicarian`. [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)\nis also supported.\n\n## Running\n\n### Systemd Service\n\nAn example `systemd` service in provided in `systemd/vicarian.service`. The\nsystemd service sets the `CAP_NET_BIND_SERVICE` flag which allows binding to\nports 80/443 without root.\n\n## Configuration\n\nVicarian currently uses the [corn](https://cornlang.dev/) configuration\nlanguage. The default configuration file is located at\n`/etc/vicarian/vicarian.corn`, but can be changed with the `--config` flag.\n\n### Basic Configuration Structure\n\nThe full configuration structure is documented in\n[CONFIGURATION.md](CONFIGURATION.md), and additional examples are available in\nthe `examples` directory, but a basic working configuration with HTTP-based\nLet's Encrypt TLS would look like:\n\n```corn\n{\n    listen = {\n        addrs = [\n            \"[::]\"  // Default; this covers IPv4 \u0026 IPv6\n        ]\n        insecure_port = 80 // Disabled by default, this will redirect to HTTPS\n        tls_port = 443 // Default\n    }\n\n    vhosts = [\n        {\n            hostname = \"example.com\"\n\n            tls = {\n                acme = {\n                    contact = \"admin@example.com\"\n                    challenge.type = \"http-01\"\n                }\n            }\n\n            backends = [\n                {\n                    context = \"/\"\n                    url = \"http://localhost:8080\"\n                }\n                {\n                    context = \"/app2\"\n                    url = \"https://localhost:8443\"\n                    trust = true\n                }\n            ]\n        }\n    ]\n}\n```\n\n## Contributing\n\nContributions, bug reports, fixes, etc. are welcome.\n\nAdditionally, a useful contributions would be to add additional DNS provider\nAPIs to the [zone-update](https://github.com/tarka/zone-update/) project.\n\n### Code of Conduct\n\nThe project follows the Rust Code of Conduct; [this can be found online](https://www.rust-lang.org/conduct.html).\n\n### Tech stack\n\nAs well as the usual dependencies Vicarian also uses:\n\n- [Pingora](https://github.com/cloudflare/pingora) for HTTP/TLS proxying.\n- [instant-acme](https://github.com/djc/instant-acme) for ACME/LetEncrypt support.\n- [path-tree](https://github.com/viz-rs/path-tree) for routing.\n- [corn](https://cornlang.dev) for configuration.\n\n### AI Contribution Policy\n\nThis project will not accept runtime code generated by AI. Generation of _draft_\ndocumentation and test code is acceptable, but should be reviewed by the\nsubmitter before raising a PR.\n\n## Security Notes\n\n- Vicarian binds to ports 80 and 443 by default, requiring appropriate permissions\n- The systemd service uses `CAP_NET_BIND_SERVICE` to bind to privileged ports without full root privileges\n- Private keys are stored in PEM format and should be properly secured\n- When using ACME with DNS-01 challenges, ensure DNS provider API credentials are stored securely\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarka%2Fvicarian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarka%2Fvicarian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarka%2Fvicarian/lists"}