103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# 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`. |