mirror of
https://codeberg.org/Codeberg/Documentation.git
synced 2026-08-15 14:53:29 -07:00
38dd33db6c
Hi! This updates Pages docs with more details on git-pages quirks and troubleshooting. Adapted from https://aartaka.me/codeberg-pages.html#git-pages Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/854 Reviewed-by: Catherine <whitequark@whitequark.org>
126 lines
3.7 KiB
Markdown
126 lines
3.7 KiB
Markdown
---
|
||
eleventyNavigation:
|
||
key: Troubleshooting
|
||
title: Troubleshooting
|
||
parent: CodebergPages
|
||
order: 99
|
||
---
|
||
|
||
## My web browser displays a security warning when I try to access my Codeberg Pages
|
||
|
||
If your user name or repository name contains a dot, your Codeberg Pages URL (<https://user.name.codeberg.page>
|
||
or <https://repo.sitory.username.codeberg.page>)
|
||
contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates.
|
||
Use the alternative URL <https://pages.codeberg.org/user.name/> as a workaround or rename you repository
|
||
(e.g. replace `.` by `_`).
|
||
|
||
## My content is not updated
|
||
|
||
The Codeberg Pages v2 server caches files under a certain size (currently 1 MiB).
|
||
Please wait a few minutes until the cache has been invalidated.
|
||
This is done to improve performance, reduce cost and server load, and save energy.
|
||
|
||
## Cloudflare and Codeberg Pages
|
||
|
||
It is important that when you use [Cloudflare](https://cloudflare.com) to manage your Domain's DNS records,
|
||
that every DNS record used for Codeberg Pages needs to be set to **DNS only** (Have a gray cloud).
|
||
This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and
|
||
redirects from other (sub-)domains.
|
||
|
||
## Troubleshooting post-git-pages errors
|
||
|
||
Given that Codeberg has moved to [git-pages](https://git-pages.org/) entirely, some behaviors changed.
|
||
Some things broke.
|
||
Including some undocumented behaviors website authors depended on.
|
||
This needs troubleshooting.
|
||
Luckily, git-pages allows troubleshooting.
|
||
|
||
Say, we add this (broken) [redirect rule](/codeberg-pages/advanced-usage/#redirects) to simulate old pages server redirection to `.html` pages:
|
||
|
||
```
|
||
/*/ /:splat.html 301
|
||
```
|
||
|
||
After committing it and opening a page like `https://example.org/hello`, we are redirected to a 404 page.
|
||
Something must be brokein in redirects.
|
||
However, we don’t know that for sure.
|
||
Need to check.
|
||
|
||
There are two ways to find out what’s broken in the website:
|
||
|
||
```
|
||
# Plain web request
|
||
curl https://example.org/.git-pages/manifest.json
|
||
# Or a dedicated tool from git-pages
|
||
git-pages-cli --debug-manifest https://example.org
|
||
```
|
||
|
||
In either case, you get huge JSONs with meta-information about the website.
|
||
The structure is roughly:
|
||
|
||
``` json
|
||
{
|
||
"repoUrl": "https://codeberg.org/.../pages.git",
|
||
"branch": "pages",
|
||
"commit": "abcdef...",
|
||
"contents": {
|
||
"": {
|
||
"type": "Directory"
|
||
},
|
||
".domains": {
|
||
// ...
|
||
},
|
||
".gitignore": {
|
||
// ...
|
||
},
|
||
"assets": {
|
||
"type": "Directory"
|
||
},
|
||
"assets/...png": {
|
||
"type": "ExternalFile",
|
||
"originalSize": "...",
|
||
"compressedSize": "...",
|
||
"data": "...",
|
||
"transform": "Identity",
|
||
"contentType": "image/png",
|
||
"gitHash": "..."
|
||
},
|
||
"index.html": {
|
||
"type": "ExternalFile",
|
||
"originalSize": "...",
|
||
"compressedSize": "...",
|
||
"data": "...",
|
||
"transform": "Zstd",
|
||
"contentType": "text/html; charset=utf-8",
|
||
"gitHash": "..."
|
||
}
|
||
// ...
|
||
},
|
||
"originalSize": "...",
|
||
"compressedSize": "...",
|
||
"storedSize": "...",
|
||
"redirects": [
|
||
{
|
||
"from": "/foo",
|
||
"to": "/bar",
|
||
"status": 301,
|
||
"force": false
|
||
},
|
||
// ...
|
||
],
|
||
"headers": [],
|
||
"basicAuth": [],
|
||
"problems": [
|
||
{
|
||
"path": "_redirects",
|
||
"cause": "rule #1 \"/*/ /:splat.html 301\": splat * must be its own final segment of the path"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
And here’s the problem, under the `"problems"` key: the redirect is malformed!
|
||
In the end, this is one of the [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations) that happened in migration.
|
||
But lamenting that is a story for another time.
|
||
Problem diagnosed through the useful git-pages manifest!
|
||
Use it to diagnose errors from now on!
|