rio/README.md

# rio

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 DNS01 challenge solver
will be created using the provider specified by `--acme-dns-provider` (`ACME_DNS_PROVIDER`). For a provider list and each provider's options, see
the [lego documentation](https://go-acme.github.io/lego/dns/). 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. rio will also spawn an unencrypted HTTP server that is bound to the host specified with `--http-host` (`HTTP_HOST`) and
the port specified with `--http-port` (`HTTP_PORT`). The functionality of this second HTTP server is to upgrade plain HTTP requests to HTTPS requests.

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
; For Let's Encrypt
_acme-challenge.cooldomain.rio. 3600    IN  CNAME   cooldomain.rio.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).

### Alternate CNAME Domains

If there is a situation where you want to use a CNAME redirect on a (sub-) domain,
where having a CNAME is not feasible, you can configure an "alternate CNAME".
This is a special TXT record that contains the "CNAME" you want to specify.

```
; Example for Bind
cooldomain.rio.                 3600    IN  A       <IPv4 of rio>
_rio-cname.cooldomain.rio.      3600    IN  TXT     "cname=user.pages.example.org"
```

### 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

See `LICENSE`.