gitea-pages

Fork of the caddy-gitea project: Gitea plugin for Caddy v2.

The project aims to have Github Pages in Gitea. For doing so it relies on a wildcard CNAME DNS entry to the gitea host.

For now markdown files (with .md extension) will also be automatically generated to HTML.

caddy-gitea
- Getting started
- Building caddy
- [Integration & deployment](#Integration with Gitea)

Getting started

Caddy config

The Caddyfile below creates a webserver listening on :3000 which will interact with gitea on https://yourgitea.yourdomain.com using agiteatoken as the token. The agiteatoken should be a token from gitea that has the necessary read rights on the repo's that you want to expose.

{
        order gitea before file_server
}
:3000
gitea {
        server https://yourgitea.yourdomain.com
        token agiteatoken
        domain pages.yourdomain.com #this is optional
}

DNS config

This works with a wildcard domain. So you'll need to make a *.pages.yourdomain.com CNAME to the server you'll be running caddy on. (this doesn't need to be the same server as gitea).

Depending on the gitea config below you'll be able to access your pages using:

http://org.pages.yourdomain.com:3000/repo/file.html (org is the organization or username)
http://org.pages.yourdomain.com:3000/repo/file.html?ref=abranch (org is the organization or username)
http://repo.org.pages.yourdomain.com:3000/file.html
http://branch.repo.org.pages.yourdomain.com:3000/file.html
http://org.pages.yourdomain.com:3000/ (if you have created a gitea-pages repo it'll be served on the root)

Gitea config

There are multiple options to expose your repo's as a page, that you can use both at the same time.

creating a gitea-pages repo with a gitea-pages branch and a gitea-pages topic
adding a gitea-pages branch to any repo of choice and a gitea-pages topic
adding a gitea-pages-allowall topic to your repo (easiest, but less secure)

gitea-pages repo

e.g. we'll use the yourorg org.

create a gitea-pages repo in yourorg org
Add a gitea-pages topic to this gitea-pages repo (this is used to opt-in your repo),
Create a gitea-pages branch in this gitea-pages repo.
Put your content in this branch. (eg file.html)

Your content will now be available on http://yourorg.pages.yourdomain.com:3000/file.html

any repo with configurable allowed branch/tag/commits

e.g. we'll use the yourrepo repo in the yourorg org and there is a file.html in the master branch and a otherfile.html in the dev branch. The master branch is your default branch.

Add a gitea-pages topic to the yourrepo repo (this is used to opt-in your repo).
Create a gitea-pages branch in this yourrepo repo.
Put a gitea-pages.toml file in this gitea-pages branch of yourrepo repo. (more info about the content below)

The gitea-pages.toml file will contain the git reference (branch/tag/commit) you allow to be exposed. To allow everything use the example below:

allowedrefs=["*"]

To only allow main and dev:

allowedrefs=["main","dev"]

Your file.html in the master branch will now be available on http://yourorg.pages.yourdomain.com:3000/yourrepo/file.html
Your file.html in the master branch will now be available on http://yourrepo.yourorg.pages.yourdomain.com:3000/file.html
Your otherfile.html in the dev branch will now be available on http://yourorg.pages.yourdomain.com:3000/yourrepo/file.html?ref=dev
Your otherfile.html in the dev branch will now be available on http://dev.yourrepo.yourorg.pages.yourdomain.com:3000/file.html

any repo with all branches/tags/commits exposed

e.g. we'll use the yourrepo repo in the yourorg org and there is a file.html in the master branch and a otherfile.html in the dev branch. The master branch is your default branch.

Add a gitea-pages-allowall topic to the yourrepo repo (this is used to opt-in your repo).

Your file.html in the master branch will now be available on http://yourorg.pages.yourdomain.com:3000/yourrepo/file.html
Your file.html in the master branch will now be available on http://yourrepo.yourorg.pages.yourdomain.com:3000/file.html
Your otherfile.html in the dev branch will now be available on http://yourorg.pages.yourdomain.com:3000/yourrepo/file.html?ref=dev
Your otherfile.html in the dev branch will now be available on http://dev.yourrepo.yourorg.pages.yourdomain.com:3000/file.html

Building caddy

As this is a 3rd party plugin you'll need to build caddy (or use the binaries). To build with this plugin you'll need to have go1.19 installed.

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest #this will install xcaddy in ~/go/bin

xcaddy build \
    --with gitea.djmil.dev/goland/gitea-pages \
    --replace gitea.djmil.dev/goland/gitea-pages=/module/gitea-pages \
    --replace gitea.djmil.dev/goland/gitea-pages/pkg/gitea=/module/gitea-pages/pkg/gitea

Integration with Gitea

Afther the release is done, gitea-pages docker image shall be availvable at the Docker Hub

version: "3"

networks:
  gitea:
    external: false

services:
  gitea:
    image: gitea/gitea:1.22.0
    restart: always
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - GITEA__database__DB_TYPE=mysql
      - GITEA__database__HOST=db:3306
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASSWD=gitea
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
    depends_on:
      - db

  db:
    image: mysql:8
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=gitea
      - MYSQL_USER=gitea
      - MYSQL_PASSWORD=gitea
      - MYSQL_DATABASE=gitea
    networks:
      - gitea
    volumes:
      - ./mysql:/var/lib/mysql

  pages:
    image: djmil/gitea-pages:0.0.1
    restart: always
    environment:
      - GITEA_HOST=http://gitea:3000
      - PAGES_DOMAIN=pages.djmil.dev
    networks:
      - gitea
    ports:
      - "3003:3003"

6.7 KiB Raw Permalink Blame History