From e46079d2b1ffc02e9e4abfc1c90ee0413343653b Mon Sep 17 00:00:00 2001
From: Wim <wim@42.be>
Date: Wed, 2 Nov 2022 01:08:01 +0100
Subject: [PATCH] Add README.md and Dockerfile

---
 Dockerfile |   8 ++++
 README.md  | 106 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 Dockerfile
 create mode 100644 README.md

diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..bdfef8e
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,8 @@
+FROM caddy:2.6-builder-alpine AS builder
+
+RUN xcaddy build \
+    --with github.com/42wim/caddy-gitea@v0.0.2
+
+FROM caddy:2.6.2
+
+COPY --from=builder /usr/bin/caddy /usr/bin/caddy
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6a0ab08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# caddy-gitea
+
+[Gitea](https://gitea.io) plugin for [Caddy v2](https://github.com/caddyserver/caddy).
+
+This allows you to have github pages (with more features) in Gitea.
+This also requires you to setup a wildcard CNAME to your gitea host.
+
+
+<!-- TOC -->
+
+- [caddy-gitea](#caddy-gitea)
+    - [Getting started](#getting-started)
+        - [Caddy config](#caddy-config)
+        - [DNS config](#dns-config)
+        - [Gitea config](#gitea-config)
+            - [gitea-pages repo](#gitea-pages-repo)
+            - [any repo](#any-repo)
+    - [Building caddy](#building-caddy)
+
+<!-- /TOC -->
+
+## 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.
+
+```Caddyfile
+{
+        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 2 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
+- adding a gitea-pages branch to any repo of choice
+
+#### gitea-pages repo
+
+e.g. we'll use the `yourorg` org.
+
+1. create a `gitea-pages` repo in `yourorg` org
+2. Add a `gitea-pages` topic to this `gitea-pages` repo (this is used to opt-in your repo),
+3. Create a `gitea-pages` branch in this `gitea-pages` repo.
+4. 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
+
+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.
+
+1. Add a `gitea-pages` topic to the `yourrepo` repo (this is used to opt-in your repo).
+2. Create a `gitea-pages` branch in this `yourrepo` repo.
+3. 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:
+
+```toml
+allowedrefs=["*"]
+```
+
+To only allow main and dev:
+
+```toml
+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>
+
+
+## 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
+go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest #this will install xcaddy in ~/go/bin
+~/go/bin/xcaddy build --with github.com/42wim/caddy-gitea@v0.0.2
+```