From 9fcd478f86232040ae0acc529a7421c2649bbc5b Mon Sep 17 00:00:00 2001 From: sjdonado Date: Sun, 2 Nov 2025 11:31:17 +0100 Subject: [PATCH] chore: simplify docs structure --- README.md | 96 ++++++++++++++++++++++++++++++++++++++--------- docs/SETUP.md | 61 ------------------------------ docs/openapi.yaml | 23 ++++++++---- 3 files changed, 95 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 549168c..6bfcac2 100644 --- a/README.md +++ b/README.md @@ -2,30 +2,92 @@ [![Docker Stars](https://img.shields.io/docker/stars/sjdonado/bit.svg)](https://hub.docker.com/r/sjdonado/bit) [![Docker Image Size](https://img.shields.io/docker/image-size/sjdonado/bit/latest)](https://hub.docker.com/r/sjdonado/bit) -Lightweight URL shortener (API-only) with minimal resource requirements. - -Highly performant: **11k req/sec**, latency 11ms, 40MiB avg memory usage (100k requests using 125 connections, [benchmark](docs/SETUP.md#benchmark)). - -Self-hosted: [Dokku](docs/SETUP.md#dokku), [Docker Compose](docs/SETUP.md#docker-compose). - -Images available on [Docker Hub](https://hub.docker.com/r/sjdonado/bit/tags). - -## Why bit? -It is feature-complete by design: simple and reliable without unnecessary bloat. Bug fixes will continue, but new features aren't planned. +## Features - Minimal tracking setup: Country, browser, OS, referer. No cookies or persistent tracking mechanisms are used beyond what's available from a basic client's request. - Includes `X-Forwarded-For` header. -- Multiple users are supported via API key authentication. Users can create, list and delete keys via the [CLI](docs/SETUP.md#cli). +- Multiple users are supported via API key authentication. Create, list and delete keys via the [CLI](docs/SETUP.md#cli). - Easy to extend, Ruby on Rails-inspired setup. -## Recommented requirements -- 100MB disk space -- 100MiB RAM -- x86_64 or ARM64 +## Why bit? + +**Fast:** **11k req/sec**, latency 11ms, 40MiB avg memory usage (100k requests using 125 connections, [benchmark](docs/SETUP.md#benchmark)). + +**Lightweight:** <100MB disk space, <100MiB RAM. + +**Self-hosted:** [Dokku](docs/SETUP.md#dokku), [Docker Compose](docs/SETUP.md#docker-compose). + +**Production ready:** Feature-complete by design, simple and reliable without unnecessary bloat. Bug fixes will continue, but new features aren't planned. + +## Run It Anywhere + +Images available on [Docker Hub](https://hub.docker.com/r/sjdonado/bit/tags). + +### Docker + +```bash +docker run \ + --name bit \ + -p 4000:4000 \ + -e ENV="production" \ + -e DATABASE_URL="sqlite3://./sqlite/data.db" \ + -e APP_URL="http://localhost:4000" \ + -e ADMIN_NAME="Admin" \ + -e ADMIN_API_KEY=$(openssl rand -base64 32) \ + sjdonado/bit + +# Create a new user +# docker exec -it bit cli --create-user=Admin +``` + +### Docker Compose + +```bash +docker-compose up + +# Optional: Generate an api key +# docker-compose exec -it app cli --create-user=Admin +``` + +### Dokku + +- Dockerfile +```dockerfile +FROM sjdonado/bit +``` + +- Over ssh + +```bash +dokku apps:create bit + +dokku domains:set bit bit.yourdomain.com +dokku letsencrypt:enable bit + +dokku storage:ensure-directory bit-sqlite +dokku storage:mount bit /var/lib/dokku/data/storage/bit-sqlite:/usr/src/app/sqlite/ + +dokku config:set bit DATABASE_URL="sqlite3://./sqlite/data.db" APP_URL=https://bit.yourdomain.com ADMIN_NAME=Admin ADMIN_API_KEY=$(openssl rand -base64 32) + +dokku ports:add bit http:80:4000 +dokku ports:add bit https:443:4000 + +# Create a new user +# dokku run bit cli --create-user=Admin +``` + +### Dokku (subnetwork) +Recommended for lower latency communication (no host network traversal) + +```bash + dokku network:create bit-net + dokku network:set bit attach-post-create bit-net + dokku network:set myapp attach-post-create bit-net +``` ## Documentation -- [API Reference](docs/API.md) -- [Setup](docs/SETUP.md) +- [API Reference](https://sjdonado.github.io/bit/) +- [Local Development](docs/SETUP.md) ## Contributing Found an issue or have a suggestion? Please follow our [contribution guidelines](CONTRIBUTING.md). diff --git a/docs/SETUP.md b/docs/SETUP.md index 967e4c4..201ff07 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -9,67 +9,6 @@ Options: --update-parsers Download all required data files ``` -## Run It Anywhere - -### Docker Compose - -```bash -docker-compose up - -# Optional: Generate an api key -# docker-compose exec -it app cli --create-user=Admin -``` - -### Docker CLI - -```bash -docker run \ - --name bit \ - -p 4000:4000 \ - -e ENV="production" \ - -e DATABASE_URL="sqlite3://./sqlite/data.db" \ - -e APP_URL="http://localhost:4000" \ - -e ADMIN_NAME="Admin" \ - -e ADMIN_API_KEY=$(openssl rand -base64 32) \ - sjdonado/bit - -# Create a new user -# docker exec -it bit cli --create-user=Admin -``` - -### Dokku - -```dockerfile -FROM sjdonado/bit -``` - -```bash -dokku apps:create bit - -dokku domains:set bit bit.donado.co -dokku letsencrypt:enable bit - -dokku storage:ensure-directory bit-sqlite -dokku storage:mount bit /var/lib/dokku/data/storage/bit-sqlite:/usr/src/app/sqlite/ - -dokku config:set bit DATABASE_URL="sqlite3://./sqlite/data.db" APP_URL=https://bit.donado.co ADMIN_NAME=Admin ADMIN_API_KEY=$(openssl rand -base64 32) - -dokku ports:add bit http:80:4000 -dokku ports:add bit https:443:4000 - -# Create a new user -# dokku run bit cli --create-user=Admin -``` - -### Dokku (same network) -Recommended for lower latency communication (no host network traversal) - -```bash - dokku network:create bit-net - dokku network:set bit attach-post-create bit-net - dokku network:set myapp attach-post-create bit-net -``` - ## Local Development ### Requirements diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 8a3d70f..7a1c946 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -1,7 +1,16 @@ -openapi: 3.1.0 +openapi: 3.0.3 info: title: Bit - URL Shortener API - description: A high-performance URL shortener service with click tracking and analytics + description: | + Fast, lightweight, self-hosted URL shortener service with minimal click tracking. + + ## Getting Started + + For setup instructions, please check the [README](https://github.com/sjdonado/bit/blob/master/README.md). + + ## Authentication + + Multiple users are supported via `X-Api-Key` headers. Create, list and delete keys via the [CLI](https://github.com/sjdonado/bit/blob/master/SETUP.md#cli). version: 1.0.0 contact: name: API Support @@ -423,24 +432,24 @@ components: example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:127.0) Gecko/20100101 Firefox/127.0 country: type: string - nullable: true description: Country code (ISO 3166-1 alpha-2) example: US + nullable: true browser: type: string - nullable: true description: Browser name example: Firefox + nullable: true os: type: string - nullable: true description: Operating system example: Mac OS X + nullable: true referer: type: string - nullable: true description: Referer domain or utm_source example: Direct + nullable: true created_at: type: string format: date-time @@ -457,9 +466,9 @@ components: next: type: integer format: int64 - nullable: true description: Cursor for next page (link/click ID) example: 12 + nullable: true Error: type: object