diff --git a/README.md b/README.md index 087d7ae..b56239b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,58 @@ -## Environment +# Codeberg Pages + +Gitea lacks the ability to host static pages from Git. +The Codeberg Pages Server addresses this lack by implementing a standalone service +that connects to Gitea via API. +It is suitable to be deployed by other Gitea instances, too, to offer static pages hosting to their users. + +**End user documentation** can mainly be found at the [Wiki](https://codeberg.org/Codeberg/pages-server/wiki/Overview) +and the [Codeberg Documentation](https://docs.codeberg.org/codeberg-pages/). + + +## Quickstart + +This is the new Codeberg Pages server, a solution for serving static pages from Gitea repositories. +Mapping custom domains is not static anymore, but can be done with DNS: + +1) add a `.domains` text file to your repository, containing the allowed domains, separated by new lines. The +first line will be the canonical domain/URL; all other occurrences will be redirected to it. + +2) add a CNAME entry to your domain, pointing to `[[{branch}.]{repo}.]{owner}.codeberg.page` (repo defaults to +"pages", "branch" defaults to the default branch if "repo" is "pages", or to "pages" if "repo" is something else): + `www.example.org. IN CNAME main.pages.example.codeberg.page.` + +3) if a CNAME is set for "www.example.org", you can redirect there from the naked domain by adding an ALIAS record +for "example.org" (if your provider allows ALIAS or similar records, otherwise use A/AAAA), together with a TXT +record that points to your repo (just like the CNAME record): + `example.org IN ALIAS codeberg.page.` + `example.org IN TXT main.pages.example.codeberg.page.` + +Certificates are generated, updated and cleaned up automatically via Let's Encrypt through a TLS challenge. + + +## Deployment + +**Warning: Some Caveats Apply** +> Currently, the deployment requires you to have some knowledge of system administration as well as understanding and building code, +> so you can eventually edit non-configurable and codeberg-specific settings. +> In the future, we'll try to reduce these and make hosting Codeberg Pages as easy as setting up Gitea. +> If you consider using Pages in practice, please consider contacting us first, +> we'll then try to share some basic steps and document the current usage for admins +> (might be changing in the current state). + +Deploying the software itself is very easy. You can grab a current release binary or build yourself, +configure the environment as described below, and you are done. + +The hard part is about adding **custom domain support** if you intend to use it. +SSL certificates (request + renewal) is automatically handled by the Pages Server, +but if you want to run it on a shared IP address (and not a standalone), +you'll need to configure your reverse proxy not to terminate the TLS connections, +but forward the requests on the IP level to the Pages Server. + +You can check out a proof of concept in the `haproxy-sni` folder, +and especially have a look at [this section of the haproxy.cfg](https://codeberg.org/Codeberg/pages-server/src/branch/main/haproxy-sni/haproxy.cfg#L38). + +### Environment - `HOST` & `PORT` (default: `[::]` & `443`): listen address. - `PAGES_DOMAIN` (default: `codeberg.page`): main domain for pages. @@ -17,23 +71,29 @@ See https://go-acme.github.io/lego/dns/ for available values & additional environment variables. - `DEBUG` (default: false): Set this to true to enable debug logging. -``` -// Package main is the new Codeberg Pages server, a solution for serving static pages from Gitea repositories. -// -// Mapping custom domains is not static anymore, but can be done with DNS: -// -// 1) add a ".domains" text file to your repository, containing the allowed domains, separated by new lines. The -// first line will be the canonical domain/URL; all other occurrences will be redirected to it. -// -// 2) add a CNAME entry to your domain, pointing to "[[{branch}.]{repo}.]{owner}.codeberg.page" (repo defaults to -// "pages", "branch" defaults to the default branch if "repo" is "pages", or to "pages" if "repo" is something else): -// www.example.org. IN CNAME main.pages.example.codeberg.page. -// -// 3) if a CNAME is set for "www.example.org", you can redirect there from the naked domain by adding an ALIAS record -// for "example.org" (if your provider allows ALIAS or similar records, otherwise use A/AAAA), together with a TXT -// record that points to your repo (just like the CNAME record): -// example.org IN ALIAS codeberg.page. -// example.org IN TXT main.pages.example.codeberg.page. -// -// Certificates are generated, updated and cleaned up automatically via Let's Encrypt through a TLS challenge. -``` + +## Contributing to the development + +The Codeberg team is very open to your contribution. +Since we are working nicely in a team, it might be hard at times to get started +(still check out the issues, we always aim to have some things to get you started). + +If you have any questions, want to work on a feature or could imagine collaborating with us for some time, +feel free to ping us in an issue or in a general Matrix chatgroup. + +You can also contact the maintainers of this project: + +- [momar](https://codeberg.org/momar) [(Matrix)](https://matrix.to/#/@moritz:wuks.space) +- [6543](https://codeberg.org/6543) [(Matrix)](https://matrix.to/#/@marddl:obermui.de) + +### First steps + +The code of this repository is split in several modules. +While heavy refactoring work is currently undergo, you can easily understand the basic structure: +The `cmd` folder holds the data necessary for interacting with the service via the cli. +If you are considering to deploy the service yourself, make sure to check it out. +The heart of the software lives in the `server` folder and is split in several modules. +After scanning the code, you should quickly be able to understand their function and start hacking on them. + +Again: Feel free to get in touch with us for any questions that might arise. +Thank you very much.