software-station/README.md

Software Station

A modern, high-performance software distribution platform for software built and hosted on Gitea. Built with Go (backend) and Svelte 5 (frontend).

Features

• Direct Gitea Integration: Automatically fetches releases, assets, and metadata from your Gitea instance.
• High-Performance Proxy: Proxies downloads with support for Resumable Downloads (HTTP Range) and modern transfer protocols.
• Security First:
  • Dynamic Bot Protection: Supports external User-Agent blocklists with automatic daily updates and local caching.
  • Enhanced Fingerprinting: Multi-header request fingerprinting (IP, UA, Accept-Language, Accept-Encoding, Sec-CH-UA) to prevent rate-limit collisions.
  • Secure Downloads: Salted SHA256 download IDs to prevent "private" repository bypasses.
  • SSRF protection for proxy requests.
  • Automatic SHA256 checksum verification for assets.
• Throttling & Rate Limiting: Intelligent download throttling (Default: 5MB/s, Speed downloaders: 1MB/s, Heavy users: 256KB/s) and global API rate limiting.
• RSS Updates: Secure XML-encoded RSS feed for tracking new software releases.
• Internationalization (i18n): Multi-language support (English, German, Italian, Russian) with automatic browser detection.

Upcoming

• S3 for software assets.
• Gitea Packages support (containers, npm, etc.).
• ISOs support (Linux distributions)
• Automatic Torrent generation and seeding for software assets.
• Software dependencies page and licenses information.
• SBOM and SPDX viewer.
• CDN support
• GPG signatures verification
• OSV integration for vulnerability scanning.
• Container scanning
• Authentication for certain software/containers
• Admin panel

Getting Started

Prerequisites

• Go 1.21+
• Node.js & pnpm (for frontend)
• A Gitea instance

Configuration

1. Software List: Create a software.txt file in the root directory. Add your Gitea repositories in Owner/Repo format:

   Quad4-Software/software-station
   Another-Owner/Project-B
   

2. Bot Blocklist: Create a ua-blocklist.txt to add URLs of User-Agent blocklists (one per line). These will be fetched and cached automatically.

3. Environment Variables:

   • GITEA_TOKEN: Your Gitea personal access token (optional, required for private repos).
   • NODE_ENV: Set to production for production builds.

Installation

1. Build the Frontend:

   cd frontend
   pnpm install
   pnpm build
   cd ..
   

2. Build and Run the Backend:

   go build -o software-station .
   ./software-station -t YOUR_TOKEN -s https://your-gitea-instance.com -ua-blocklist ua-blocklist.txt
   

Customization

Adding Locales

To add a new language:

1. Create a JSON file in frontend/src/lib/i18n/locales/ (e.g., fr.json).
2. Register the locale in frontend/src/lib/i18n/index.ts.

Changing Security Rules

Modify internal/security/constants.go or ua-blocklist.txt to adjust:

• ForbiddenPatterns: Block specific URL patterns.
• BotUserAgents: Block specific scrapers or bots (static list).
• ua-blocklist.txt: External lists for dynamic bot blocking.
• DefaultDownloadLimit: Adjust the global download speed limit.

UI Themes

The frontend uses Tailwind CSS. You can customize the look and feel in frontend/tailwind.config.js and frontend/src/app.css.

Development

Run the backend and frontend separately for a better development experience:

# Backend (with live reload using Air or just go run)
go run main.go

# Frontend (Vite dev server)
cd frontend
pnpm dev

Testing

We maintain a high test coverage (>60%). Run the test suite:

go test -v -coverpkg=./... ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Quad4. All rights reserved.