Gelbooru-Go

A lightweight, JavaScript-free (for now, this may change) private frontend for Gelbooru written in Go with caching and security features. The project uses only Go standard library, keeping dependencies minimal.

Instances

Public instances of Gelbooru-Go:

Country	Address	Rating
Germany	gel.bloat.cat	General

Requirements

• Latest version of Go

Deployment

Docker Compose

Copy compose.example.yaml to compose.yaml and .env.example to .env, then edit them as needed:

cp compose.example.yaml compose.yaml
cp .env.example .env

Edit .env file with your configuration. You can obtain your API key and user ID from Gelbooru Account Options.

Then run:

docker compose up -d

Without Docker

Clone the repository:

git clone https://git.bloat.cat/vlnst/gelbooru-go
cd gelbooru-go

Set environment variables and run:

export API_KEY=your_api_key_here
export USER_ID=your_user_id_here
export PORT=3000
export POSTS_LIMIT=30
export RATING=general
make run

You can automate this using systemd or another init system.

Configuration

Required Variables

• API_KEY - Your Gelbooru API key (obtain from Account Options)
• USER_ID - Your Gelbooru user ID (obtain from Account Options)

Optional Variables

• PORT - Server port (default: 3000)
• POSTS_LIMIT - Posts per page, 1-100 (default: 30)
• RATING - Maximum allowed rating (default: general)

Rating System

Ratings follow a hierarchy: general → sensitive → questionable → explicit

Setting RATING=explicit allows all ratings (general, sensitive, questionable, and explicit). Setting RATING=questionable allows general, sensitive, and questionable, but not explicit. And so on.

Performance & Security

Caching

• API responses: Cached for 5 minutes
• Images: Cached for 60 minutes
• Large files (>10MB) and videos are streamed instead of cached

Security Features

• Security headers: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection
• Request deduplication: Multiple concurrent requests for the same post share a single API call (singleflight pattern)
• URL validation: Proxy endpoint only allows Gelbooru domains
• Content-Type validation: Only allowed media types are served
• Size limits: Maximum image size 50MB, URL length 2048 chars, tags length 500 chars

Contributing

This project follows Semantic Versioning and uses Conventional Commits for commit messages.

Commit Message Format

Follow the Conventional Commits specification:

• fix: - Bug fixes (patch version bump)
• feat: - New features (minor version bump)
• feat!: or fix!: - Breaking changes (major version bump)
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• perf: - Performance improvements
• test: - Test additions or changes
• chore: - Other changes (build, config, etc.)

Examples:

• fix: resolve memory leak in cache cleanup
• feat: add support for custom rating filters
• feat!: change API response format

Code Quality

Before submitting code:

1. Format code: go fmt
2. Run linter: golangci-lint run