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 in the Codeberg Documentation.

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. If the branch name contains slash characters, you need to replace "/" in the branch name to "~"): 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.

Documentation serve and build locally

Pages uses mdBook and mdbook-toc to build and serve its documentation. Some section of the documentation have been referenced here for ease of use.

mdBook Installation mdbook-toc Installation

Once installed and sourced users may mdbook serve pages-server/doc/ from a terminal of their choosing.

Documentation linting set up

To run the tools used in this repo you will need NodeJS on your machine. The required version will change over time, but in general it is recommended to use at least the latest LTR release.

You'll also need PNPM. The easiest way to install it on most systems is to use the command corepack enable, which is part of NodeJS. However depending on your system you may prefer to use a package manager.

Once you have Node and PNPM installed, just run pnpm install from the root of this repo to fetch the dependencies and set up the Git pre-commit hook.

# Install/enable PNPM
corepack enable

# Clone this repo (or your fork of it)
git clone git@codeberg.org:forgejo/docs
cd docs

# Install the dependencies
pnpm install

Every time you pull the repo or checkout a different branch, you should run pnpm install again to update the dependencies.

Previewing changes

pnpm run preview

This command will clone the website repo and launch a local development server. The current docs branch will be opened in the browser.

The URL to the documentation preview looks like http://localhost:4321/docs/{branch}/ where {branch} is the name of the current branch from which the preview is run.

Modifications can be made to the docs while the dev server is running, and the preview will live-reload.

Linting and formatting

We use two linters to check that all content is formatted in a consistent way. Most of the rules are checked using remark-lint, whilst some stylistic consistency is enforced using Prettier.

To run both linters and display any warnings in the terminal, use the following command:

pnpm run lint

Prettier is also able to automatically format the code according to its rules. To do so, use the following command. Be aware that it can occasionally break things, so be sure to check what it changes.

pnpm run format:prettier

There is currently no way to automatically format the code to according to the rules configured for remark-lint, however the pre-commit hook should prevent badly-formatted content from being committed.

Chat for admins & devs

matrix: #gitea-pages-server:matrix.org

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 examples/haproxy-sni folder, and especially have a look at this section of the haproxy.cfg.

If you want to test a change, you can open a PR and ask for the label build_pr_image to be added. This will trigger a build of the PR which will build a docker image to be used for testing.

Environment Variables

• ACME_ACCEPT_TERMS (default: use self-signed certificate): Set this to "true" to accept the Terms of Service of your ACME provider.
• ACME_API (default: https://acme-v02.api.letsencrypt.org/directory): set this to https://acme.mock.director to use invalid certificates without any verification (great for debugging). ZeroSSL might be better in the future as it doesn't have rate limits and doesn't clash with the official Codeberg certificates (which are using Let's Encrypt), but I couldn't get it to work yet.
• ACME_EAB_KID & ACME_EAB_HMAC (default: don't use EAB): EAB credentials, for example for ZeroSSL.
• ACME_EMAIL (default: noreply@example.email): Set the email sent to the ACME API server to receive, for example, renewal reminders.
• ACME_USE_RATE_LIMITS (default: true): Set this to false to disable rate limits, e.g. with ZeroSSL.
• DNS_PROVIDER (default: use self-signed certificate): Code of the ACME DNS provider for the main domain wildcard. See https://go-acme.github.io/lego/dns/ for available values & additional environment variables.
• ENABLE_HTTP_SERVER (default: false): Set this to true to enable the HTTP-01 challenge and redirect all other HTTP requests to HTTPS. Currently only works with port 80.
• GITEA_API_TOKEN (default: empty): API token for the Gitea instance to access non-public (e.g. limited) repos.
• GITEA_ROOT (default: https://codeberg.org): root of the upstream Gitea instance.
• HOST & PORT (default: [::] & 443): listen address.
• LOG_LEVEL (default: warn): Set this to specify the level of logging.
• NO_DNS_01 (default: false): Disable the use of ACME DNS. This means that the wildcard certificate is self-signed and all domains and subdomains will have a distinct certificate. Because this may lead to a rate limit from the ACME provider, this option is not recommended for Gitea/Forgejo instances with open registrations or a great number of users/orgs.
• PAGES_DOMAIN (default: codeberg.page): main domain for pages.
• RAW_DOMAIN (default: raw.codeberg.page): domain for raw resources (must be subdomain of PAGES_DOMAIN).

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

You can also contact the maintainer(s) of this project:

• crapStone (Matrix)

Previous maintainers:

• momar (Matrix)
• 6543 (Matrix)

First steps

The code of this repository is split in several modules.

The cmd folder holds the data necessary for interacting with the service via the cli. The heart of the software lives in the server folder and is split in several modules.

Again: Feel free to get in touch with us for any questions that might arise. Thank you very much.

Test Server

Make sure you have golang v1.21 or newer and just installed.

run just dev now these pages should work:

• https://cb_pages_tests.localhost.mock.directory:4430/images/827679288a.jpg
• https://momar.localhost.mock.directory:4430/ci-testing/
• https://momar.localhost.mock.directory:4430/pag/@master/
• https://mock-pages.codeberg-test.org:4430/README.md

Profiling

This section is just a collection of commands for quick reference. If you want to learn more about profiling read this article or google golang profiling.

First enable profiling by supplying the cli arg --enable-profiling or using the environment variable EENABLE_PROFILING.

Get cpu and mem stats:

go tool pprof -raw -output=cpu.txt 'http://localhost:9999/debug/pprof/profile?seconds=60' &
curl -so mem.txt 'http://localhost:9999/debug/pprof/heap?seconds=60'

More endpoints are documented here: https://pkg.go.dev/net/http/pprof