DOCSEARCHbyAlgolia
Submit Docs

chhoto-url

repository·main·Indexed 21 days ago

https://github.com/sintan1729/chhoto-url

A high-performance, minimal-footprint self-hosted URL shortener written in Rust using Actix Web. It features a lightweight frontend, privacy-focused hit counting, and an ACID-compliant SQLite database. Key capabilities include custom slugs, link expiry, QR code generation, and a JSON-RPC adjacent API with X-API-Key authentication. The service is highly configurable via environment variables and supports flexible deployment modes, including a frontend-less configuration.

Tokens
10.1K
Snippets
26
Records
59
Agent score
74%

What's inside chhoto-url

  1. Overview of Chhoto URL

    main

    Chhoto URL is a lightweight, self-hosted URL shortener designed for simplicity and speed. It is written in Rust (using Actix Web) and features a minimal frontend (HTML/Vanilla JS/Pure CSS).

    Key characteristics:

    • Extremely lightweight: Docker images are <8.5 MB (Alpine) and RAM usage is typically <10 MB.
    • Privacy-focused: Hit counting is performed without tracking user data.
    • Feature-rich but minimal: Supports custom slugs, link expiry, link editing, custom notes, QR code generation, and a JSON-RPC adjacent API.
    • Flexible deployment: Can be run in 'public mode' (anyone can add links) or restricted mode. It can also run without a frontend entirely.

  2. Understand Chhoto URL database backups

    main

    Chhoto URL manages its own SQLite backups automatically:

    • Initialization Backup: Created during the first setup (.init1, .init2, etc.).
    • Daily Backups: Taken daily between 3am and 4am (.daily1, .daily2, etc.).
    • Location: Backups are stored in a backups directory located in the same directory as the database file.
    • Retention: The system keeps up to 3 initialization backups and 7 daily backups, purging older ones automatically.

  3. Authenticate with Chhoto URL API

    main

    Chhoto URL supports two authentication methods: API Key validation and Cookie validation.

    API Key Validation (Recommended for programs)

    To use API key validation, set the CHHOTO_API_KEY environment variable on your server. When making requests, include the key in the X-API-Key header. All responses using this method are JSON encoded.

    To generate a secure 128-character API key on Linux, use:

    tr -dc A-Za-z0-9 < /dev/urandom | head -c 128

    Cookie Validation

    If you are using password-based authentication, you must first authenticate via the /api/login endpoint to obtain a cookie, then use that cookie for subsequent requests.

    1. Login and save cookie:
      curl -X POST -d "<your-password>" -c cookie.txt http://localhost:4567/api/login
    2. Use cookie in requests: Add -b cookie.txt to your curl commands.

    Note: The /api/expand route is not accessible via cookie validation; it requires an API key.

    curl -X POST -d "<your-password>" -c cookie.txt http://localhost:4567/api/login

  4. Core Features of Chhoto URL

    main

    Chhoto URL provides the following capabilities:

    • URL Management: Shorten URLs to random links, specify custom slugs, or set automatic expiry times.
    • Redirection: Instant redirection to the long URL without intermediate landing pages.
    • Link Metadata: Attach custom notes to links and filter the UI by short link, long link, or notes.
    • API & Automation: Robust JSON-RPC adjacent API supporting API keys and hashed passwords.
    • Customization: Serve a custom landing page and configure the base URL of your website for local generation.
    • Storage: Uses an ACID-compliant SQLite database.
    • Security: Supports basic authentication via password. Note: Authentication is not encrypted in transport; it is highly recommended to use a reverse proxy like Caddy for SSL/TLS.

  5. Install Chhoto URL using Docker Compose

    main

    The recommended method for deployment is using docker compose. The repository provides a sample compose.yaml file in the deploy/ directory that contains a basic deployment configuration.

    To start the service, navigate to the directory containing your compose.yaml and run:

    docker compose up -d

    Important Note for SQLite Users: If you are using a custom location for CHHOTO_DB_URL and have enabled WAL mode, ensure you mount a whole directory rather than a single file to the container to prevent potential data corruption.

  6. Choose the right Docker image flavor

    main

    Chhoto URL provides several image flavors depending on your needs:

    • Default (latest or scratch): The smallest possible image, built from scratch. Best for production.
    • Alpine (latest-alpine or alpine): Slightly larger, but includes basic Unix tools useful for debugging or interactive inspection.
    • Dev (dev): Built on alpine and intended for testing only. Do not use these for production workloads.

    Images are built for linux/amd64, linux/arm64, linux/arm/v7, and linux/riscv64 architectures and are compatible with Docker, Podman, and other OCI-compliant engines.

  7. Important Configuration and Usage Notes

    main

    When deploying Chhoto URL, keep the following technical recommendations in mind:

    • Database Performance: It is highly recommended to enable WAL mode for the SQLite database.
    • Scaling Slugs: If you plan to host more than a few thousand links, use the CHHOTO_SLUG_STYLE UID with a CHHOTO_SLUG_LENGTH of 16 or more to prevent generation collisions.
    • Protocol Restrictions: By default, only https, http, ftp, and magnet protocols are allowed for long links. You can extend this using CHHOTO_EXTRA_PROTOCOLS.
    • Data Safety: For mission-critical use, maintain regular versioned backups of the SQLite database.
    • Demo Instance: A public demo is available at demo.chhoto.link (Password: chhoto-url-demo-pass), but note that the database is cleared every 15 minutes.

  8. Build and run Chhoto URL with Docker CLI

    main

    You can manually build and run the Chhoto URL image using the docker build and docker run commands.

    1. Build the image

    For the default x86_64-unknown-linux-musl target:

    docker build -f build/Containerfile . -t chhoto-url

    For other architectures (arm64, arm/v7, or riscv64), specify the target using a build argument. Ensure the target is a musl variant:

    docker build -f build/Containerfile . -t chhoto-url --build-arg target=<desired-target>

    2. Run the image

    Basic run (with password):

    docker run -p 4567:4567 \
    -e CHHOTO_PASSWORD="password" \
    -d chhoto-url:latest

    Run with persistent SQLite database: To persist your data, create a local database file and mount a data directory to the container:

    touch ./urls.sqlite
docker run -p 4567:4567 \
    -e CHHOTO_PASSWORD="password" \
    -v ./data:/data \
    -e CHHOTO_DB_URL=/data/urls.sqlite \
    -d chhoto-url:latest
    docker build -f build/Containerfile . -t chhoto-url

docker run -p 4567:4567 \
    -e CHHOTO_PASSWORD="password" \
    -d chhoto-url:latest

  9. Explore 3rd party Chhoto URL tools

    main

    Several unofficial tools are available to integrate Chhoto URL into your workflow. These are maintained by the community and are not officially supported by the Chhoto URL project. If you encounter issues, please report them to the respective tool maintainers.

    Browser Extension

    An unofficial browser extension maintained by @SolninjaA allows for easy URL shortening directly from your browser. View Repository

    Raycast Extension

    An unofficial Raycast extension maintained by @paranoidPhantom enables efficient URL shortening via Raycast. Get it from the Raycast Store

    FreeBSD Port

    An unofficial FreeBSD port maintained by @jcpsantiago is available for installing Chhoto URL on FreeBSD systems. View Port Details

    NixOS Package

    An unofficial NixOS package maintained by @Defelo is available for NixOS users. Search NixOS Packages

  12. Deploy Chhoto URL to Kubernetes using Helm

    main

    To deploy to a Kubernetes cluster, use the provided Helm chart. The chart assumes cert-manager is installed for TLS management.

    1. Copy the template values file: cp deploy/helm-chart/values.yaml deploy/helm-chart/my-values.yaml
    2. Edit my-values.yaml to set your password, fqdn, and letsencryptmail.
    3. Run the Helm upgrade command:
    cd helm-chart
helm upgrade --install chhoto-url . -n chhoto-url --create-namespace -f my-values.yaml