caddygitea

package module
v0.0.0-...-e77b2b6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 18 Imported by: 0

README

Caddy plugin: Gitea

A Caddy plugin that runs Gitea, the version control server, inside Caddy: one Caddy binary is the web server and Gitea, with no second process and no port of its own. Caddy does TLS, HTTP/2 and HTTP/3 in front of it. Part of Weddy, Caddy with the Gitea and WeKan plugins.

{
	gitea {
		work_path /var/lib/gitea
	}
}

git.example.org {
	gitea
}
xcaddy build --with github.com/wekan/caddy-gitea-plugin

How: a patches repository with the needed parts of Gitea in it

Like wekan/gitea-patches, this repository follows upstream Gitea with patches - but because a Caddy plugin is a Go module that go and xcaddy fetch from its repository, the Gitea code it builds is committed here, in gitea/. releases/sync-gitea.sh makes it:

  1. upstream Gitea, with wekan/gitea-patches - its complete Finnish translation and its patches - applied as commits by gitea-patches' own apply-patches.sh;
  2. this repository's dist/gitea/ patches on top, as commits;
  3. Gitea's frontend built;
  4. releases/copy-gitea.py copies only the needed parts into gitea/: the packages this plugin's code imports and everything they import, computed with go list -deps for every operating system Weddy is built for - no tests, cmd/, frontend sources, docs or tools - with imports moved into this module, and the templates, translations and built frontend embedded from assets/ directories, so a plain go build with CGO off and no build tags has all of Gitea's web server. gitea/SOURCE.md records the exact commits.

gitea/ is generated: change Gitea upstream, in gitea-patches or in dist/gitea/, and sync again.

Patch Why
embedded-in-a-host Inside Caddy, Gitea must not handle Caddy's signals - a SIGHUP would make it "restart" by re-executing Caddy's binary - nor shut down the HTTP server after its install page, which is Caddy's
security-hardening What code scanning found worth changing: the container tag list's allocation from ?n=, two int64 to int conversions that wrap on 32-bit platforms, and credentials in the access log. The rest of the alerts and why they stay are in the Hall of Fame

Modules

Module What it does
gitea (app) starts Gitea in Caddy's process from its app.ini, in the background - its database migrations do not hold up Caddy. Gitea's state is process-wide, so it starts once, keeps running across Caddy configuration reloads, and stops - gracefully, within stop_timeout - when Caddy exits
http.handlers.gitea serves a site from it: Gitea answers itself, including its 404s; 503 with Retry-After while Gitea starts. Before Gitea is installed, it serves Gitea's install page, and switches to Gitea itself when the installation is done
Option Meaning Default
work_path Gitea's WORK_PATH Gitea's default
custom_path Gitea's custom directory <work_path>/custom
config Gitea's app.ini <custom_path>/conf/app.ini
stop_timeout how long Gitea gets to stop when Caddy exits 30s

The Gitea settings are Gitea's own, in app.ini - ROOT_URL should be the site's address. Changing work_path, custom_path or config needs a restart of Caddy, not only a reload. Gitea maintains ~/.ssh/authorized_keys of the user it runs as - the user Caddy runs as - unless app.ini says SSH_CREATE_AUTHORIZED_KEYS_FILE = false or another SSH_ROOT_PATH.

For other plugins

supervisor runs a program as a supervised child process and proxy serves a site from it - for programs that stay separate processes. caddy-wekan-plugin runs WeKan with them.

Releases

Releases are tags of this module, v0.<YYYYMMDD>.<HHMM> - xcaddy build --with github.com/wekan/caddy-gitea-plugin@<tag>. Go accepts only v0 and v1 versions for this module path, so Gitea's version is in each release's title and notes rather than in its tag. The source attached as caddy-gitea-plugin-source-with-history.zip (the repository with its git history) and caddy-gitea-plugin-source-without-history.zip.

Tests

CGO_ENABLED=0 go test ./...

They run a real Caddy with the embedded Gitea on a new SQLite database: 503 while it starts, then its login page - in Finnish for a Finnish browser - its embedded assets and its own 404; and the supervisor with real child processes.

Gitea's own tests are not in gitea/, so go get of the plugin does not download them. releases/copy-gitea-tests.py copies them - with the packages only they need and their fixtures - into a COPY of this repository, from the Gitea source gitea/ was made from; Weddy's tests/gitea/run.sh makes that copy and runs them, CGO off and no build tags, the way Weddy builds Gitea in.

License

This repository's own files are MIT - see LICENSE. Gitea is MIT too: gitea/LICENSE.

Maintainer and contributor rules are in WeKan's CLAUDE.md and AGENTS.md, which cover every repository WeKan clones into its .tools/ directory.

Documentation

Overview

Package caddygitea is a Caddy plugin that runs Gitea, the version control server, INSIDE Caddy: the needed parts of Gitea's source are in this repository (gitea/), copied from upstream Gitea with wekan/gitea-patches and this repository's patches applied (releases/sync-gitea.sh), so one Caddy binary serves Gitea itself.

  • the app "gitea" starts Gitea in Caddy's process, from its app.ini;
  • the handler "gitea" (http.handlers.gitea) serves a site from it - no proxy, no second process, no port of its own.

Caddyfile:

{
	gitea {
		work_path /var/lib/gitea
	}
}
git.example.org {
	gitea
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App

type App struct {
	// WorkPath is Gitea's WORK_PATH: repositories, data and custom/ are below it.
	WorkPath string `json:"work_path,omitempty"`
	// CustomPath is Gitea's custom directory. Default: <work_path>/custom.
	CustomPath string `json:"custom_path,omitempty"`
	// Config is Gitea's app.ini. Default: <custom_path>/conf/app.ini.
	Config string `json:"config,omitempty"`
	// StopTimeout is how long Gitea gets to finish its work when Caddy exits.
	// Default 30s.
	StopTimeout caddy.Duration `json:"stop_timeout,omitempty"`
	// contains filtered or unexported fields
}

App runs Gitea inside Caddy.

func (App) CaddyModule

func (App) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*App) Provision

func (a *App) Provision(ctx caddy.Context) error

Provision keeps the logger.

func (*App) Ready

func (a *App) Ready() bool

Ready reports whether Gitea serves requests.

func (*App) Start

func (a *App) Start() error

Start starts Gitea in the background: Caddy does not wait for its database migrations; the handler answers 503 until Gitea is ready.

func (*App) Stop

func (a *App) Stop() error

Stop stops Gitea when Caddy exits; on a configuration reload Gitea keeps running.

func (*App) UnmarshalCaddyfile

func (a *App) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile reads the global option:

gitea {
	work_path    <dir>
	custom_path  <dir>
	config       <app.ini>
	stop_timeout <duration>
}

type Handler

type Handler struct{}

Handler serves a site from the Gitea running in Caddy.

func (Handler) CaddyModule

func (Handler) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*Handler) Provision

func (h *Handler) Provision(ctx caddy.Context) error

Provision checks that the gitea app is configured.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request, _ caddyhttp.Handler) error

ServeHTTP lets Gitea answer, or answers 503 while it starts.

func (*Handler) UnmarshalCaddyfile

func (h *Handler) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

UnmarshalCaddyfile: the directive takes no arguments, "gitea".

Directories

Path Synopsis
gitea
modules/citation
Package citation formats CITATION.cff files, ported from the formatters of ruby-cff 1.3.0
Package citation formats CITATION.cff files, ported from the formatters of ruby-cff 1.3.0
modules/log
Package log provides logging capabilities for Gitea.
Package log provides logging capabilities for Gitea.
modules/queue
Package queue implements a specialized concurrent queue system for Gitea.
Package queue implements a specialized concurrent queue system for Gitea.
modules/web/binding
Package binding binds form, multipart and JSON request data to structs and validates them by their "binding" tags.
Package binding binds form, multipart and JSON request data to structs and validates them by their "binding" tags.
modules/zstd
Package zstd provides a high-level API for reading and writing zstd-compressed data.
Package zstd provides a high-level API for reading and writing zstd-compressed data.
routers/api/v1
Package v1 Gitea API
Package v1 Gitea API
routers/private
Package private contains all internal routes.
Package private contains all internal routes.
services/notifications
Package notifications wraps activities_model notification-status mutations with the matching real-time push, so route handlers cannot forget either side.
Package notifications wraps activities_model notification-status mutations with the matching real-time push, so route handlers cannot forget either side.
services/pubsub
Package pubsub fans real-time events out to local WebSocket subscribers.
Package pubsub fans real-time events out to local WebSocket subscribers.
Package proxy sends HTTP requests to a supervised child process with Caddy's own reverse proxy - WebSockets, streaming and the X-Forwarded-* headers included - and answers 503 with Retry-After while the child is not accepting connections yet, so a client sees "starting" rather than a gateway error.
Package proxy sends HTTP requests to a supervised child process with Caddy's own reverse proxy - WebSockets, streaming and the X-Forwarded-* headers included - and answers 503 with Retry-After while the child is not accepting connections yet, so a client sees "starting" rather than a gateway error.
Package supervisor runs one program as a child process of Caddy: it starts it, restarts it when it exits on its own, knows when it accepts connections, and stops it - and every process it started - when Caddy stops.
Package supervisor runs one program as a child process of Caddy: it starts it, restarts it when it exits on its own, knows when it accepts connections, and stops it - and every process it started - when Caddy stops.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL