A simple static page service for Forgejo/Gitea.

Repo setup

Everything in branch static-pages (if you have not changed it by assigning --branch flag) will be served as-is.

There are two mode you can use: serve mode and webhook mode.

Serve mode

Serve mode starts an HTTP server listens on specified port. When you visit http://ip:port/user/repo/path/to/file, it ask forgejo server for path/to/file in branch static-pages of repository user/repo via api, then forward the response to client.

This mode is good for simple setup, like, you have small number of viewers, or you use other powerful cache/proceting service like Cloudflare.

Webhook mode

Webhook mode is a tool which helps you to download latest content via git. You'll have to setup a webhook in forgejo server in order to notify it when to download new content. You have to have git binary in your path.

To serve downloaded pages, you'll have to use a web server like Nginx.

Example

forgejo-pages serve --token my-secret-token --server https://git.example.com --bind :8080 --branch static-pages

forgejo-pages listen --user myuser --token my-secret-token --server https://git.example.com --bind :8080 --branch static-pages --dir ./data

Flags can be assigned through environmental variables like PAGES_BIND, PAGES_BRANCH, or config file

bind=":8080"
server="https://git.example.com"
token="my-secret-token"

Take care about permissions of the API token. For serve mode, repositories the key cannot read will return error. For webhook mode, it will failed to download (clone/pull) new content.

Use docker

docker run -p 8080:8080 --user 1000:1000 ronmi/forgejo-pages serve -s https://git.example.com -k my-secret-token

docker run -p 8080:8080 --user 1000:1000 -v `pwd`/data:/data ronmi/forgejo-pages:git listen -u myuser -k my-secret-token -s https://git.example.com -a :8080 -b static-pages -d /data

Serve mode could use latest tag, a minimal image contains only libc, CA certificates, timezone data and page server binary.

Webhook mode should use git tag.

FAQ

Can I use user.example.com/repo/path format?

Use reverse proxy, Nginx for example:

server {
    server_name ~^(?<user>[^.]+)\.example\.com$;
    location / {
        proxy_pass http://1.2.3.4:5678/$user$uri;
    }
}

Will it support SSL for security?

No, use reverse proxy or webhook mode. You might also need LetsEncrypt or Cloudflare to apply for a free SSL certificate. If you need all-in-one solution, take a look at https://codeberg.org/Codeberg/pages-server/

Will it support caching

No. Serve mode does provide very basic cache (etag, last-modified and related HTTP headers) as it just forward request to your git server. If your need more, use reverse proxy or webhook mode. If you need all-in-one solution, take a look at https://codeberg.org/Codeberg/pages-server/

License

MPLv2. There is a copy of source at https://github.com/Ronmi/forgejo-pages