76 lines
2.9 KiB
Markdown
76 lines
2.9 KiB
Markdown
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
|
|
|
|
```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.
|
|
|
|
# FAQ
|
|
|
|
### 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
|