giteapages

README

INFO: preliminary documentation ... more to come

Overview

This is an all in one pages server for Gitea. With default settings it works and uses similar/same conventions as Github Pages.

You can operate it in 2 modes, either simple (default) or classic (similar to how Github Pages operates).

In simple mode no special DNS setup is required and the access to the hosted sides are always according to the pattern http(s)://<your-server-hostname>/<organization>/<repository>

In classic mode the access to the pages goes according to these two patterns: http(s)://<organization>.<your-server-hostname>/<repository> or http(s)://<organization>.<your-server-hostname> (with default configuration this serves the content of the repo named <organization>.github.io of the organization) This requires that you setup a wildcard CNAME in DNS for your gitea host (see below for more details). You also need a wildcard HTTPS certificate if you want to run with HTTPS.

Usage

To run the server in simple mode you need a minimal configuration (filename Caddyfile) like this (replace your-gitea-server and gitea_access_token):

{
	order gitea-pages before file_server
}
:8080
gitea-pages {
	server https://your-gitea-server
	token gitea-access-token
}

Afterward you can simply run:

./caddy run --config Caddyfile

Configuration

These are the possible configuration options with their defaults:

{
	order gitea-pages before file_server
}
:8080
gitea-pages {
	server https://your-gitea-server
	token gitea-access-token
        pages_branch gh-pages
        postfix_pages_repository github.io
        url_scheme simple
}
log {
	level debug
}

For url_scheme defines the operation mode, it accepts simple and classic.

Development

The project is implemented as an extension for Caddy . More details can be found at: https://caddyserver.com/docs/extending-caddy

Build

To build the server xcaddy need to be installed.

# Installing xcaddy
go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest

To build the server binary simply run

# Build a specific version
xcaddy build --with github.com/simongregorebner/caddy-gitea@v0.0.1

# Build with specific commit (that was pushed to github)
xcaddy build --with github.com/simongregorebner/caddy-gitea@f4a6a77

# Build locally
xcaddy build --with github.com/simongregorebner/caddy-gitea=.

Docker

To build the server and create a docker image you can use:

docker build -t gitea-pages .

# cross platform build
docker build --platform=linux/amd64 -t gitea-pages .

Testing

If you are running/testing the server in simple mode:

curl "http://localhost:8080/<organization>/<repository>[/index.html | /<path>]"

If running in classic mode:

# testing organization repo
curl -H "Host: <organisation>.<your testserver name>" "http://localhost:8080/"
# testing a specific repo of the organization
curl -H "Host: <organisation>.<your testserver name>" "http://localhost:8080/<repository>"

Acknowledgements

This project is an extremely simplified rewrite of the https://github.com/42wim/caddy-gitea project.

Documentation

Index

• type GiteaPagesModule
  • func (GiteaPagesModule) CaddyModule() caddy.ModuleInfo
  • func (module *GiteaPagesModule) Provision(ctx caddy.Context) error
  • func (module GiteaPagesModule) ServeHTTP(writer http.ResponseWriter, request *http.Request, _ caddyhttp.Handler) error
  • func (module *GiteaPagesModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

Types

type GiteaPagesModule

type GiteaPagesModule struct {
	Logger                 *zap.Logger   `json:"-"`
	GiteaClient            *gitea.Client `json:"-"`
	Server                 string        `json:"server,omitempty"`
	Token                  string        `json:"token,omitempty"`
	PagesBranch            string        `json:"pages_branch,omitempty"`
	PostfixPagesRepository string        `json:"postfix_pages_repository,omitempty"`
	URLScheme              string        `json:"url_scheme,omitempty"`
}

GiteaagesModule implements gitea plugin.

func (GiteaPagesModule) CaddyModule

func (GiteaPagesModule) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*GiteaPagesModule) Provision

func (module *GiteaPagesModule) Provision(ctx caddy.Context) error

Provision provisions gitea client.

func (GiteaPagesModule) ServeHTTP

func (module GiteaPagesModule) ServeHTTP(writer http.ResponseWriter, request *http.Request, _ caddyhttp.Handler) error

ServeHTTP performs gitea content fetcher.

func (*GiteaPagesModule) UnmarshalCaddyfile

func (module *GiteaPagesModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile unmarshals a Caddyfile.