forgejo-pages

KO | EN

gitlite — search

#python #react #machine-learning #deep-learning #linux #nodejs #java #cli #kubernetes #vue #pytorch #mcp #ios #open-source

(★ 28)

A simple static page service for Forgejo/Gitea.

forgejo-pages Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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/protecting 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

```toml
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.

# Build from source

Requires Golang toolchain installed.

```sh
# build binary
go build
# optionally build docker image for serve mode (need docker)
docker build -t forgejo-pages --load .
# optionally build docker image for webhook mode (need docker)
docker build -t forgejo-pages -f git.dockerfile --load .
```

# FAQ

### MIME/Content-Type problem.

For general cases like hosting simple website (blog, project doc, ...), a new option `--auto-mime/-m` has been introduced in commit 842b0bf (2026/06/08) to save your life. It detects MIME type by file extension.

If `-m` does not fit your need, use a reverse proxy to customize or swith to full-feature solution like https://codeberg.org/Codeberg/pages-server/ instead.

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

Use reverse proxy, Nginx for example:

```nginx
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

forgejo-pages

forgejo-pages Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

forgejo-pages

forgejo-pages Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README