Codeberg/pages-server: This repository is in maintenance mode (in favor of git-pages, see README) · Codeberg Pages Server v2 – w

Codeberg/pages-server: This repository is in maintenance mode (in favor of git-pages, see README) · Codeberg Pages Server v2 – with custom domain support, per-repo pages using the "pages" branch, caching and much more! - Codeberg.org
Codeberg
pages-server
Fork
You've already forked pages-server
53
Code
Issues
111
Pull requests
Releases
31
Packages
Wiki
Activity
This repository is in maintenance mode (in favor of git-pages, see README) · Codeberg Pages Server v2 – with custom domain support, per-repo pages using the "pages" branch, caching and much more!
codeberg
forgejo
github-pages
golang
selfhost
server
woodpecker-ci
351
commits
branches
36
tags
138
MiB
Go
95.7%
HTML
1.5%
Just
1.1%
Dockerfile
0.9%
Nix
0.8%
Find a file
2026-04-21 11:36:02 +02:00
.gitea
/ISSUE_TEMPLATE
Meta: Redirect user support to Codeberg/Community (
#277
2024-01-18 20:35:32 +00:00
.helix
chore: make project helix ready
2025-06-10 23:24:49 +02:00
.vscode
Add config file and rework cli parsing and passing of config values (
#263
2024-02-15 16:08:29 +00:00
.woodpecker
chore(deps): update woodpeckerci/plugin-docker-buildx docker tag to v6.0.4 (
#541
2026-01-20 02:34:35 +01:00
cli
feat: make logging interval configurable (
#511
2025-09-10 14:22:10 +02:00
config
feat: make logging interval configurable (
#511
2025-09-10 14:22:10 +02:00
examples
/haproxy-sni
Add prettier config and format files (
#319
2024-04-28 20:47:04 +00:00
html
Allow serving custom error page (
#393
2024-11-17 16:28:52 +00:00
integration
Add config file and rework cli parsing and passing of config values (
#263
2024-02-15 16:08:29 +00:00
server
fix crash when most active IP list cannot be saturated
2026-04-21 11:19:07 +02:00
.ecrc
Add editorconfig, fix files and lint via ci
2022-11-11 23:51:45 +01:00
.editorconfig
Add editorconfig, fix files and lint via ci
2022-11-11 23:51:45 +01:00
.env-dev
Add config file and rework cli parsing and passing of config values (
#263
2024-02-15 16:08:29 +00:00
.envrc
setup direnv (
#433
2025-02-15 19:32:29 +00:00
.gitignore
setup direnv (
#433
2025-02-15 19:32:29 +00:00
.golangci.yml
Add cert store option based on sqlite3, mysql & postgres (
#173
2023-02-10 03:00:14 +00:00
.prettierrc.json
Add prettier config and format files (
#319
2024-04-28 20:47:04 +00:00
.yamllint.yaml
Add yamllint (
#321
2024-04-28 21:48:07 +00:00
Dockerfile
chore: update golang (
#431
2025-02-15 19:08:08 +00:00
example_config.toml
Rename gitea to forge in cli args and env variables (
#339
2024-05-26 14:45:03 +00:00
FEATURES.md
Add prettier config and format files (
#319
2024-04-28 20:47:04 +00:00
flake.lock
feat: make logging interval configurable (
#511
2025-09-10 14:22:10 +02:00
flake.nix
chore: make project helix ready
2025-06-10 23:24:49 +02:00
go.mod
Revert "chore(deps): update golang deps non-major (
#528
)"
2026-04-21 11:36:02 +02:00
go.sum
Revert "chore(deps): update golang deps non-major (
#528
)"
2026-04-21 11:36:02 +02:00
Justfile
Add option to start http server for profiling (
#323
2024-04-30 19:50:03 +00:00
LICENSE
Release under EUPL v. 1.2
2021-03-17 01:21:50 +01:00
main.go
Add config file and rework cli parsing and passing of config values (
#263
2024-02-15 16:08:29 +00:00
README.md
Clarify maintenance notice
2026-02-21 13:45:25 +01:00
renovate.json
chore(config): migrate renovate config (
#526
2025-10-20 16:27:28 +02:00
treefmt.toml
chore: make project helix ready
2025-06-10 23:24:49 +02:00
README.md
Codeberg Pages
This code is in maintenance mode:
#399
Codeberg Pages itself is in the process of migrating to the new
git-pages
server
and is still a fully supported feature of Codeberg.
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
and 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:
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.
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.
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.
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:
): set this to
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
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:
): 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
).
Custom Error Page
A custom error page template can be served by creating
custom/error.html
Data available to the template includes:
{{ .StatusCode }}
: The HTTP status code (e.g. 404)
{{ .StatusText }}
: The textual name associated with the status code (e.g. Not Found)
{{ .Message }}
: The reason for the error
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
Architecture is explained
in the wiki.
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:
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: