Press / to focus
Codeberg Documentation

Getting Started with Codeberg
What is Codeberg? Your First Steps on Codeberg Install Git Your First Repository The Basics of Issue Tracking Integrated Wiki Email Settings Licensing on Codeberg Frequently Asked Questions
Collaborating with Others
Citable Code Pull requests and Git flow Invite Collaborators Create and Manage an Organization Repository Permissions Resolve Conflicts
Working with Git Repositories
Using .gitignore Configuring Git Clone & Commit via CLI Clone & Commit via Web Merge multiple commits into one Tags and Releases Working with large files
Writing in Markdown
Introduction to Markdown Using Links Topics Preformatted Text Using Lists Using Images Tables in Markdown Markdown FAQ
Security
Setting up two-factor authentication Adding an SSH key to your account Verifying you're connected to Codeberg using SSH fingerprints Adding a GPG key to your account
Codeberg Pages
Using Custom Domains Troubleshooting Example: Docs as Code with Sphinx Pushing output from SSGs into Codeberg Pages Redirects
Advanced Usage
Generating an Access Token Migrating Repositories Using Webhooks
Working with Codeberg's CI
Using Forgejo Actions (Self-hosted)
Integrations with Other Services
Integrating with Keycloak Integrating with Matrix Integrating with LiberaPay Integrating with Read the Docs
Codeberg Translate
Getting started Introduction to Weblate Manual Component configuration
Improving Codeberg
Contributing Code
Improving the Documentation
Style Guide How to create a new article? Can I preview my article? How to make screenshots for Codeberg Documentation? Documentation Contributor FAQ
Contact

Using Custom Domains

Instead of using the codeberg.page domain, you can also purchase your own domain from a domain registrar of your choice and configure it to serve content from Codeberg Pages.

Known pitfalls for failed certificate errors

For custom domains, two things are required:

  • a .domains file in the repository and branch where your files reside which you want to publish via Codeberg Pages. The file should contain a list of all domains that shall be usable to access that repository, according to the following rules:

    • One domain per line, you can leave lines empty and comment out lines with #.
    • The first domain is the main domain, all other domains in the file will be redirected to the first one.
    • The rest of the list includes all relevant *.codeberg.page domains for the specific repository.

  • a DNS record pointing to one of the following targets, depending on where your static files reside:


Why do I need all of these DNS records?

To understand how the Pages server serves content, you need to know that a user browsing your custom domain just sends "Hey, I want to see yourdomain.com" to the server. But the server might not know that it is responsible for yourdomain.com and it cannot just serve all domains in the world. So to find out if the server is responsible for yourdomain.com it will check the DNS entries of yourdomain.com. If it returns something with codeberg.page (according to the domain schemes mentioned below) then it knows which respository to check for the .domains file and your content.

Setting the DNS record

There are several ways DNS records for your website can be setup in order to tell the Pages server your repository location. For all of the options it is important that the Pages server knows where to look for the .domains file and your content. Depending on from where you want to serve your files, there is a naming scheme for the domain:

Domain Scheme Pages URL
username.codeberg.page https://username.codeberg.page
which will serve codeberg.org/username/pages
reponame.username.codeberg.page https://username.codeberg.page/reponame
which will serve codeberg.org/username/reponame
branchname.reponame.username.codeberg.page https://username.codeberg.page/reponame/@branchname/
which will serve codeberg.org/username/reponame/src/branch/branchname

We assume for the following description, that you want to serve your website with and without www in front. If you are on a subdomain already (like myproject.yourdomain.com), you can skip the www.yourdomain.com CNAME entry.

Warning

When setting up DNS records with many registrars, any domain added to the Domain or Host option is automatically appended onto the domain the records are being made for.

For example, if your domain is example.com, entering www will mean the record refers to www.example.com.

Therefore, in this guide, you may need to replace references to just your domain name (e.g. example.com) with @ and anything.example.com (i.e. any subdomain) with just anything.

Option 1: CNAME record

The easiest and recommended way is to just setup a CNAME record for your domain, pointing to the mentioned above locations. In the end, it should look like this:

Domain Type Data
yourdomain.comCNAMEreponame.username.codeberg.page
www.yourdomain.comCNAMEreponame.username.codeberg.page

Warning

With a CNAME record everything on this domain is delegated to codeberg.page, which means you cannot setup your own email address with this method.

If you need email or others services, you have to use one of the remaining options.

Option 2: ALIAS record

If you cannot use a CNAME record to configure the target you can use this method, which needs two entries instead of one.

  • First you need to specify which server should be serving your website. Similar to CNAME you can use an ALIAS record. The difference between an CNAME record is, that the DNS server directly responds with the ip address and not the codeberg.page domain. Therefore you need to add a second entry, so that the pages server knows what to serve under this domain.
  • Second, you need to setup a TXT record which contains the information from the CNAME entry which is your repository location as mentioned above. For example [[branch.]repo.]user.codeberg.page.

In the end it should look like this:

Domain Type Data
yourdomain.comALIAScodeberg.page
yourdomain.comTXTreponame.username.codeberg.page
www.yourdomain.comCNAMEreponame.username.codeberg.page

Option 3: A/AAAA record

If your service provider does not support ALIAS records you can also use A records and AAAA records instead.

  • First you need to specify which server should be serving your website. You can do this by setting an A record for IPv4 and an AAAA record for IPv6 which contains the ip address of the Codeberg Pages server. The servers' ip addresses are:
    • A record which contains the IPv4 value 217.197.91.145
    • AAAA record which contains the IPv6 value 2001:67c:1401:20f0::1
  • Second, you need to setup a TXT record which contains the information from the CNAME entry which is your repository location as mentioned above. For example [[branch.]repo.]user.codeberg.page.

In the end, it should look like this:

Domain Type Data
yourdomain.comA217.197.91.145
yourdomain.comAAAA2001:67c:1401:20f0::1
yourdomain.comTXTreponame.username.codeberg.page
www.yourdomain.comCNAMEreponame.username.codeberg.page

Examples

The following sub-sections include a few examples of the different alternatives, assuming the following:

  • we can add/modify DNS records in domain example.com.
  • Our Codeberg username is frida, and we want to publish pages for:
    • frida/pages, with a Personal static site inside branch pages;
    • frida/colormix, with a Project site (again, inside branch pages).

All considerations regarding a Personal site also apply to an Organization site, so these two cases will be addressed together.

Personal (or Organization) site, third level domain

In this case, we want our Personal pages available at the URL https://myself.example.com.

The .domains file contains the following:

myself.example.com
frida.codeberg.page
pages.frida.codeberg.page
pages.pages.frida.codeberg.page

For the DNS configuration:

  • if CNAME can be used, one single DNS record will suffice:

    • name myself.example.com, type CNAME, data frida.codeberg.page

  • otherwise, if ALIAS can be used, two DNS records will be needed:

    • name myself.example.com, type ALIAS, data codeberg.page
    • name myself.example.com, type TXT, data frida.codeberg.page

  • otherwise, A/AAAA records must be used, together with one TXT record:

    • name myself.example.com, type A, data 217.197.91.145
    • name myself.example.com, type AAAA, data 2001:67c:1401:20f0::1
    • name myself.example.com, type TXT, data frida.codeberg.page

Personal/Organization site, apex domain

In this case, we want our Personal/Organization pages available at the URL https://example.com.

The .domains file contains the following:

example.com
frida.codeberg.page
pages.frida.codeberg.page
pages.pages.frida.codeberg.page

For the DNS configuration, the CNAME SHOULD NOT be used, so:

  • if ALIAS can be used, two DNS records will be needed:

    • name example.com, type ALIAS, data codeberg.page
    • name example.com, type TXT, data frida.codeberg.page

  • otherwise, A/AAAA records must be used, together with one TXT record:

    • name example.com, type A, data 217.197.91.145
    • name example.com, type AAAA, data 2001:67c:1401:20f0::1
    • name example.com, type TXT, data frida.codeberg.page

Project site, third-level domain

In this case, we want our Project pages available at the URL https://colormix-app.example.com.

The .domains file contains the following:

colormix-app.example.com
colormix.frida.codeberg.page
pages.colormix.frida.codeberg.page

For the DNS configuration:

  • if CNAME can be used, one single DNS record will suffice:

    • name colormix-app.example.com, type CNAME, data colormix.frida.codeberg.page

  • otherwise, if ALIAS can be used, two DNS records will be needed:

    • name colormix-app.example.com, type ALIAS, data codeberg.page
    • name colormix-app.example.com, type TXT, data colormix.frida.codeberg.page

  • otherwise, A/AAAA records must be used, together with one TXT record:

    • name colormix-app.example.com, type A, data 217.197.91.145
    • name colormix-app.example.com, type AAAA, data 2001:67c:1401:20f0::1
    • name colormix-app.example.com, type TXT, data colormix.frida.codeberg.page

Project site, apex domain

In this case, we want our Project pages available at the URL https://example.com.

Note

This would be incompatible with using the apex example.com for other purposes, e.g. for the Personal/Organization example discussed before.

The .domains file contains the following:

example.com
colormix.frida.codeberg.page
pages.colormix.frida.codeberg.page

For the DNS configuration, CNAME SHOULD NOT be used:

  • if ALIAS can be used, two DNS records will be needed:

    • name example.com, type ALIAS, data codeberg.page
    • name example.com, type TXT, data colormix.frida.codeberg.page

  • otherwise, A/AAAA records must be used, together with one TXT record:

    • name example.com, type A, data 217.197.91.145
    • name example.com, type AAAA, data 2001:67c:1401:20f0::1
    • name example.com, type TXT, data colormix.frida.codeberg.page

Hey there! 👋 Thank you for reading this article!

Is there something missing, or do you have an idea on how to improve the documentation? Do you want to write your own article?

You're invited to contribute to the Codeberg Documentation at its source code repository, for example, by adding a pull request or joining in on the discussion in the issue tracker.

For an introduction on contributing to Codeberg Documentation, please have a look at the Contributor FAQ.

© Codeberg Docs Contributors. See LICENSE