git-gemini-forge 0.3.0

A simple Gemini server that serves a read-only view of public repositories from a Git forge.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# git-gemini-forge

A simple [Gemini](https://geminiprotocol.net/) server that bridges public repositories from a Git forge onto Geminispace. Inspired by masalachai's [gemini-git-browser](https://github.com/masalachai/gemini-git-browser).

## Under Construction

> [!WARNING]
> This project is under active construction, and is missing basic features. Inputs and environment variables may change at any time until v1.0.0.

Features:

- Proxy a given git forge's API.
- List a forge's public users.
- List a given user's repositories.
- List a given repository's branches.
- List a given repository's tree.
- Docker image

What still needs done:

- Present source files.
- Support other APIs than Forgejo.

## Installation

### Docker

Create a `compose.yaml` file like the following:

```yaml
services:
  git-gemini-forge:
    image: git.average.name/averagehelper/git-gemini-forge:latest
    container_name: git-gemini-forge
    restart: unless-stopped
    environment:
      - PLATFORM_TYPE=forgejo
      - FORGE_URL=http://localhost:3000
    volumes:
      - "./.certs:/app/.certs:ro"
    network_mode: "host"
```

See also the example [`compose.yaml`](./compose.yaml) file provided here.

If your git forge is on a different network from the host, then omit `network_mode` and specify a `ports` map:

```yaml
services:
  git-gemini-forge:
    # [...]
    ports:
      - "1965:1965"
```

Then run:

```sh
docker compose pull
docker compose up -d
```

### Cargo

This crate is published on our own package registry. With [`cargo`](https://www.rust-lang.org/tools/install) installed, run the following:

```sh
cargo install --index sparse+https://git.average.name/api/packages/AverageHelper/cargo/ git-gemini-forge
```

Also available from [crates.io](https://crates.io/crates/git-gemini-forge):

```sh
cargo install git-gemini-forge
```

Then run with:

```sh
FORGE_URL=http://localhost:3000 git-gemini-forge
```

### Build from source

Clone this project using `git`. Then, with [`cargo`](https://www.rust-lang.org/tools/install) installed, run the project using:

```sh
FORGE_URL=http://localhost:3000 cargo run --release
```

## Certificates

### For local development

Create TLS certificates like so:

```sh
mkdir -p .certs
cd .certs
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 1103760 -nodes -subj '/CN=localhost'
```

> [!IMPORTANT]
> Change the `'/CN=localhost'` part to your expected domain when using in production.

Note that the `-days` arg in the command above sets the cert to expire sometime around the year 3024. This is sufficient for use with Gemini capsules or local development, but not much else.

The `<project>/.certs` directory must contain `key.pem` and `cert.pem`, or the server will panic.

## Disclaimer

I am not responsible for misuse of this tool. The intent is for Forgejo admins to host this capsule alongside their own Forgejo installation, pinging the forge's API via localhost. While proxy via HTTPS is supported, proxying external git forges that you do not own is quite rude when done without permission. Be sure to obtain consent before bogging down someone else's server with proxy traffic.