Gemini Gateway

A lightweight, self-hosted web proxy that allows you to browse the Gemini protocol internet (Geminispace) directly from any standard web browser. It fetches Gemini pages, parses Gemtext, and renders them into clean, accessible HTML.

Features

• Protocol Translation: Acts as a bridge between HTTP/HTTPS clients and gemini:// servers.
• Native Gemtext Rendering: Fully parses Gemtext, transforming headings, lists, blockquotes, links, and preformatted text into styled HTML.
• Database Caching: Utilises MariaDB to cache pages and URLs, reducing external network requests and optimising load times.
• Robust Security:
  • SSRF Protection: Prevents Server-Side Request Forgery by blocking resolutions to private and loopback IP addresses.
  • TLS Certificate Pinning: Employs a Trust-On-First-Use (TOFU) model, storing and verifying TLS certificate fingerprints for hostnames to prevent MITM attacks.
  • Security Headers: Implements strict middleware headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy).
• State Handling: Natively handles Gemini status codes, including redirects (3x) and input requests (10, 11 - including sensitive input masking).
• Dockerised: Fully containerised application environment with a docker-compose.yml for straightforward self-hosting.

Architecture & Tech Stack

• Backend: Go (1.22)
• Database: MariaDB 11
• Frontend: HTML, vanilla JavaScript, and CSS (Server-Side Rendered via Go html/template)
• Deployment: Docker & Docker Compose

Prerequisites

If you are deploying via Docker, ensure you have the following installed:

• Docker
• Docker Compose

Installation & Setup

The recommended method for deploying Gemini Gateway is using Docker Compose.

1. Clone the repository:

   git clone https://github.com/yourusername/gemini-gateway.git
   cd gemini-gateway
   

2. Configure Environment Variables: Copy the example environment file and modify it as needed to secure your database credentials.

   cp .env.example .env
   

   Example .env configuration:

   APP_PORT=8080
   DB_USER=gemini
   DB_PASSWORD=your_secure_password
   DB_NAME=gemini_gateway
   DB_ROOT_PASSWORD=your_secure_root_password
   

3. Start the services: Run the following command to build the Go binary and start both the application and the database containers in the background.

   docker-compose up -d --build
   

4. Access the Gateway: Open your web browser and navigate to http://localhost:8080 (or whichever port you specified in APP_PORT).

Manual Build (Without Docker)

If you prefer to run the application directly on your host machine:

1. Ensure Go 1.22+ and a MariaDB/MySQL server are installed.
2. Create the database and user to match your .env configuration.
3. Install dependencies and build the binary:

   go mod download
   go build -o gemini-gateway .
   

4. Export the required environment variables:

   export DB_HOST=localhost
   export DB_USER=gemini
   export DB_PASS=gemini
   export DB_NAME=gemini_gateway
   

5. Run the application:

   ./gemini-gateway
   

Usage

Once the application is running, use the search bar on the homepage to enter a Gemini URL (e.g., gemini://geminiprotocol.net). The gateway will fetch the server's certificate, verify it, download the content, parse the Gemtext, and return a rendered HTML page to your browser. You can navigate through Geminispace by clicking the => styled links.

License

This project is released into the public domain under the CC0 1.0 Universal License. You can copy, modify, distribute, and perform the work, even for commercial purposes, all without asking permission.