diff --git a/.gitignore b/.gitignore index 3035107..45e076a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,2 @@ -.idea/ -.cache/ -*.iml -key-database.pogreb/ -acme-account.json -build/ -vendor/ -pages -certs.sqlite -.bash_history +book + diff --git a/README.md b/README.md index 029ba9b..7fffdfe 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,7 @@ The Codeberg Pages Server addresses this lack by implementing a standalone servi 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](https://codeberg.org/Codeberg/pages-server/wiki/Overview) -and the [Codeberg Documentation](https://docs.codeberg.org/codeberg-pages/). +**End user documentation** can mainly be found in the [Codeberg Documentation](https://docs.codeberg.org/codeberg-pages/). Get It On Codeberg @@ -105,7 +104,6 @@ Previous maintainers: ### 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. diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..1d45ef3 --- /dev/null +++ b/book.toml @@ -0,0 +1,24 @@ +[book] +authors = ["Codeberg Contributors"] +language = "en" +multilingual = true +src = "src" +title = "Pages" + +[preprocessor.toc] +command = "mdbook-toc" +renderer = ["html"] +max-level = 5 + +[output.html] +curly-quotes = true +git-repository-icon = "fa-git" + +[output.html.playground] +editable = true + +[output.html.search] +enable = true + +[build] +create-missing = false \ No newline at end of file diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..a8c3841 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,8 @@ +# Pages + +[Index of Contents](title-page.md) +---- +[Also Used At](also-used-at.md) +[Architecture](architecture.md) +[Overview](overview.md) +[Repo Configuration](repo-configuration.md) diff --git a/src/also-used-at.md b/src/also-used-at.md new file mode 100644 index 0000000..dd9e1b4 --- /dev/null +++ b/src/also-used-at.md @@ -0,0 +1,3 @@ +# Also Used At + +- https://gitnet.page/ (https://gitnet.fr) \ No newline at end of file diff --git a/src/architecture.md b/src/architecture.md new file mode 100644 index 0000000..4082b9c --- /dev/null +++ b/src/architecture.md @@ -0,0 +1,24 @@ +# Architecture + +| package | description | depends on | +|--|--|--| +| main.go | init app in cmd/* | cmd, server/version | +| cmd | start app, read config from args and env vars, validate args | server/{cache,certificates,gitea,handler}, github.com/urfave/cli +| server/cache | create key/value cache based con settings | github.com/OrlovEvgeny/go-mcache | +| server/database | create cert database witch persist certs for main and custom domain | github.com/go-acme/lego/v4/{certcrypto,certificate}, xorm.io/xorm | +| server/certificates | request, mock, manage certificates via acme | server/{cache,context,database,dns,gitea,utils}, github.com/go-acme/lego/v4/{registration,providers/dns,upstream} | +| server/context | smal wrapper for net/http response and requests | server/utils | +| server/dns | handle dns lookups for custom domains | server/cache | +| server/gitea | handle all gitea-backend calls and it's caching | server/cache, code.gitea.io/sdk/gitea | +| server/handler | take all http(s) requests and determine how they need to be threated (default pages, custom domain, ...). it does however not serve stuff | html,server/{cache,context,dns,gitea,upstream,version} | +| server/upstream | try to serve stuff based on args from handler | html,server/{cache,context,gitea} | +| server/utils | general purpose functions | | +| server/version | just store the program version | | + +## Concepts + +Each package creates a client that others can use e.g.: + +- server/gitea -> GiteaClient +- server/certificates -> AcmeClient +- ... diff --git a/src/overview.md b/src/overview.md new file mode 100644 index 0000000..f94456a --- /dev/null +++ b/src/overview.md @@ -0,0 +1,40 @@ +# Codeberg Pages + +Codeberg Pages users can easily deploy static websites on Codeberg using Git. + +The Codeberg Pages server responds to four different URLs: + +- https://raw.codeberg.org/username/reponame/: raw content, uses correct MIME types (HTML is forbidden though) & is accessible with CORS. +- https://username.codeberg.page: user page, points the default branch of a user's or organization's pages repository +- https://username.codeberg.page/reponame/: repo page, points to the pages branch of the repository +- https://example.org: custom domain, points to a repo of choice as outlined below + +In all cases append a branch is done using an @ (e.g. +https://username.codeberg.page/@develop/README.md). + +## Custom Domains + +WARNING: Custom domains aren't fully tested yet and users may run into Let's +Encrypt Rate Limits for their domains. It is recommended to try it out on an +unused subdomain first so as to complete one request, and if it fails, contact the +maintainers who can +check what the problem is. A better process for such errors is being worked on. + +Currently known pitfalls: + +- Either not have a `CAA` record, or explicitly allow letsencrypt.org + +For custom domains, two things are required: + +- A `.domains` file in the repository (in the branch in question), containing a list of domains that shall be usable to access that repository: + - One domain per line, leaving lines empty and comment out lines with #. + - All domains (including *.codeberg.page) will be redirected to the first domain in that file. + +- A `CNAME` record pointing to one of the following targets: + - username.codeberg.page → https://username.codeberg.page + - reponame.username.codeberg.page → https://username.codeberg.page/reponame/ + - branchname.reponame.username.codeberg.page → https://username.codeberg.page/reponame/@branchname/ + +If a `CNAME` record cannot be used to configure the target (e.g. for a zone +root), a A/AAAA/ALIAS record to codeberg.page with an additional TXT record +for the target (just as shown above for `CNAME` records) can be used. diff --git a/src/repo-configuration.md b/src/repo-configuration.md new file mode 100644 index 0000000..6218ae8 --- /dev/null +++ b/src/repo-configuration.md @@ -0,0 +1,3 @@ +# .domains + +List allowed custom domains, first entry is default and all other domains will be redirected to it. \ No newline at end of file diff --git a/src/title-page.md b/src/title-page.md new file mode 100644 index 0000000..c4addea --- /dev/null +++ b/src/title-page.md @@ -0,0 +1,6 @@ +## Index of Contents + +[Also Used At](also-used-at.md)\ +[Architecture](architecture.md)\ +[Overview](overview.md)\ +[Repo Configuration](repo-configuration.md) \ No newline at end of file