chore: Add documentation

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       <IPv4>
+*.pages		3600	IN	AAAA	<IPv6>
+```
+
+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 `<user>.pages.example.org/some-repo/files.html`, rio will
+first see if the repository `some-repo` exists for the user `<user>` on the configured
+Gitea server. If it does, then rio will try to proxy the file `files.html` from
+the repository `<user>/some-repo`. If that repository does not exist, then
+rio will try the repository `<user>/<user>.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 `<user>.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   <user>.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