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.

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