fork from d7z-project/caddy-gitea-pages
This commit is contained in:
“xHuPo”
parent
50a258ea59
commit
9d86fd33c6
86 changed files with 2452 additions and 4500 deletions
208
README.md
208
README.md
|
|
@ -1,141 +1,83 @@
|
|||
# Codeberg Pages
|
||||
# Gitea Pages
|
||||
|
||||
[](https://opensource.org/license/eupl-1-2/)
|
||||
[](https://ci.codeberg.org/Codeberg/pages-server)
|
||||
<a href="https://matrix.to/#/#gitea-pages-server:matrix.org" title="Join the Matrix room at https://matrix.to/#/#gitea-pages-server:matrix.org">
|
||||
<img src="https://img.shields.io/matrix/gitea-pages-server:matrix.org?label=matrix">
|
||||
</a>
|
||||
[English (Google TR)](./README_en.md) | 中文
|
||||
|
||||
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.
|
||||
> 参照 Github Pages 实现的 Gitea Pages
|
||||
|
||||
**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/).
|
||||
## 安装说明
|
||||
|
||||
<a href="https://codeberg.org/Codeberg/pages-server"> <img src="https://codeberg.org/Codeberg/GetItOnCodeberg/raw/branch/main/get-it-on-blue-on-white.svg" alt="Get It On Codeberg" width="250"/> </a>
|
||||
|
||||
## 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.
|
||||
|
||||
## Chat for admins & devs
|
||||
|
||||
[matrix: #gitea-pages-server:matrix.org](https://matrix.to/#/#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](https://codeberg.org/Codeberg/pages-server/src/branch/main/examples/haproxy-sni/haproxy.cfg#L38).
|
||||
|
||||
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.directory> 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](#chat-for-admins--devs).
|
||||
|
||||
You can also contact the maintainer(s) of this project:
|
||||
|
||||
- [crapStone](https://codeberg.org/crapStone) [(Matrix)](https://matrix.to/#/@crapstone:obermui.de)
|
||||
|
||||
Previous maintainers:
|
||||
|
||||
- [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.
|
||||
The [Architecture is explained](https://codeberg.org/Codeberg/pages-server/wiki/Architecture) 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](https://go.dev) v1.21 or newer and [just](https://just.systems/man/en/) 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](https://go.dev/doc/diagnostics) 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:
|
||||
此处需要用到 `xcaddy` 工具，使用如下命令生成 Caddy 执行文件，
|
||||
如果 `xcaddy` 不存在，需先前往 [caddyserver/xcaddy](https://github.com/caddyserver/xcaddy/releases) 安装 `xcaddy`,
|
||||
同时安装好 Golang 1.22
|
||||
|
||||
```bash
|
||||
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'
|
||||
xcaddy build v2.8.4 --with github.com/d7z-project/caddy-gitea-pages
|
||||
# 列出当前模块
|
||||
./caddy list-modules | grep gitea
|
||||
```
|
||||
|
||||
More endpoints are documented here: <https://pkg.go.dev/net/http/pprof>
|
||||
当前项目也提供 `linux/amd64` 和 `linux/arm64` 的镜像:
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/d7z-project/caddy-gitea-pages:nightly
|
||||
```
|
||||
|
||||
具体配置说明参考 `docker.io/library/caddy` 镜像。
|
||||
|
||||
## 配置说明
|
||||
|
||||
安装后 Caddy 后, 在 `Caddyfile` 写入如下配置:
|
||||
|
||||
```conf
|
||||
{
|
||||
order gitea before file_server
|
||||
}
|
||||
|
||||
:80
|
||||
gitea {
|
||||
# Gitea 服务器地址
|
||||
server https://gitea.com
|
||||
# Gitea Token
|
||||
token please-replace-it
|
||||
# 默认域名，类似于 Github 的 github.io
|
||||
domain example.com
|
||||
}
|
||||
```
|
||||
|
||||
其中，token 需要如下权限：
|
||||
|
||||
- `organization:read`
|
||||
- `repository:read`
|
||||
- `user:read`
|
||||
|
||||
更详细的配置可查看 [Caddyfile](./Caddyfile)
|
||||
|
||||
## 使用说明
|
||||
|
||||
仓库 `https://gitea.com/owner/repo.git` 对应示例配置中的 `owner.example.com/repo`
|
||||
|
||||
如需访问 `CNAME` 配置的域名，则需要先访问仓库对应的 `<owner>.example.com/<repo>` 域名, 此操作只需完成一次。
|
||||
|
||||
**注意**： 需要仓库存在 `gh-pages` 分支和分支内存在 `index.html` 文件才可访问，如果配置后仍无法访问可重启 Caddy 来清理缓存。
|
||||
|
||||
### 文件回退策略
|
||||
|
||||
- URL 末尾为 `/` 时将自动追加 `index.html`
|
||||
- 未找到文件时，如果存在 `404.html` 将使用此文件，响应 404 状态码
|
||||
- 如果仓库带有 `routes-history` 和 `routes-hash` 标签时，默认回退使用 `index.html`, 同时返回 200 状态码
|
||||
|
||||
## TODO
|
||||
|
||||
- [x] 支持 CNAME 自定义路径 (仅适用于 HTTP 模式，不处理 acme 相关的内容)
|
||||
- [x] 支持内容缓存
|
||||
- [ ] 优化并发模型和处理竞争问题
|
||||
- [ ] 支持 Http Range 断点续传
|
||||
- [ ] 支持 oauth2 登录访问私有页面
|
||||
|
||||
## 致谢
|
||||
|
||||
此项目参考了 [42wim/caddy-gitea](https://github.com/42wim/caddy-gitea)
|
||||
|
||||
## LICENSE
|
||||
|
||||
此项目使用 [Apache-2.0](./LICENSE)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue