From 5181aed0b8947b003026cd17803c10e547594869 Mon Sep 17 00:00:00 2001 From: "Alexander \"PapaTutuWawa" Date: Mon, 1 Jan 2024 16:28:54 +0100 Subject: [PATCH] chore: Add documentation --- README.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1b27f7e..fc4f134 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,87 @@ # rio -A (somewhat) Github Pages compatible Webserver using the Gitea API. +A webserver similat to Github Pages using the Gitea API. Supports running in HTTP-only +mode and running in HTTPS mode with automatic certificates using ACME HTTP01 challenges. + +## Setup +### DNS + +Assuming your pages domain is `pages.example.org`, you should add a wildcard +DNS record (if your provider supports it) to allow clients to resolve any +`*.pages.example.org` record: + +``` +; Example for an authoritative Bind nameserver +*.pages 3600 IN A +*.pages 3600 IN AAAA +``` + +If you have setup a CAA record to lock ACME certificates to a certain +CA, make sure you allow certificates using the HTTP01 challenge type from the +ACME CA configured in rio. + +### rio + +To run rio, you can use environment variables or commandline flags. To see them, +run `rio --help` or look at the [main file](./cmd/rio/main.go). + +If you run with `--acme-disable` (or `ACME_DISABLE=1`), then rio will not set up +an HTTPS server and run with HTTP only on the configured host and port. In this +configuration, only `--gitea-url` (`GITEA_URL`) and `--pages-domain` (`PAEGS_DOMAIN`) +are required. + +If you run without `--acme-disable` (default), then rio will set up a HTTPS server +to listen on the configured host and port. Additionally, a HTTP-only server will be +set up listening to `${ACME_HOST}:${ACME_PORT}`, responsible for HTTP01 ACME +challenges. In this mode, `--acme-email` (`ACME_EMAIL`; The email to use to register +an ACME account), `--acme-file` (`ACME_FILE`; Path to the file where ACME account data is stored), `--certs-file` (`CERTS_FILE`; Path to the file where certificates +are stored in) are additionally required. `--acme-server` (`ACME_SERVER`) should also +be set to your ACME CA's directory URL as this option defaults to the +[Let's Encrypt Staging Environment](https://letsencrypt.org/docs/staging-environment/). Note that using this optional implies that you accept your +configured ACME CA's Terms of Service. + +You can also run with `--debug` (`DEBUG_ENABLE=1`) to enable debug logging. + +## Usage +### Plain Domains + +When a user tries to access `.pages.example.org/some-repo/files.html`, rio will +first see if the repository `some-repo` exists for the user `` on the configured +Gitea server. If it does, then rio will try to proxy the file `files.html` from +the repository `/some-repo`. If that repository does not exist, then +rio will try the repository `/.pages.example.org` next and look for the +file `some-repo/files.html`. + +Note that the files MUST reside in the repository's `pages` branch. Otherwise, rio +will not find the files. + +### CNAME Domains + +If you don't want to use `.pages.example.org` and instead prefer to use your own +domain (`cooldomain.rio`), you can add a CNAME record on your domain, redirecting to +the pages domain: + +``` +; Example for Bind +cooldomain.rio. 3600 IN CNAME .pages.example.org +``` + +This additionally requires your repository to have a file named `CNAME` that contains +the domain to use (`cooldomain.rio` in this case). + +### Repository Redirects + +If you have multiple repositories with pages (and you use a CNAME), you can additionally +add a TXT record to tell rio what repository to look for. For example, the following +TXT record will tell rio to use the repository `example-repository` whenever +`example-repository.rio` is accessed: + +``` +; Example for Bind +_rio-pages.example-repository.rio. 3600 IN TXT "repo=example-repository" +``` + +For this to work, it is important that the record's value starts with `repo=`. ## License