4.0 KiB
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).
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.