cmd/rio | ||
internal | ||
.gitignore | ||
go.mod | ||
go.sum | ||
LICENSE | ||
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.
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. 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
See LICENSE
.