Kutt

Kutt is a lightweight, self‑hosted URL shortener written in Node.js that prioritizes developer ergonomics. It exposes a RESTful API, supports custom domains, and offers granular control over link attributes (password protection, expiration, description). The core goal is to provide a zero‑configuration experience while still allowing full customization through environment variables and a rich set of configuration files.

Key Features & Technical Capabilities

• Custom Domains – Resolve *.kutt.it to user‑defined domains via DNS CNAME or A records, with automatic SSL provisioning through Let’s Encrypt.
• Link Metadata – Store per‑link metadata such as password, expiration timestamp, and description in the database; enforce access control at redirect time.
• Analytics – Increment counters for hits, store referrer and user‑agent data; expose aggregated stats via /api/stats endpoints.
• Admin API – CRUD operations for users, links, and domains; role‑based access control (admin vs. regular user).
• Webhook Support – Trigger external HTTP callbacks on link creation, update, or deletion.
• Extensibility – Themes and UI customizations via CSS/HTML templates; plugin hooks for adding new authentication providers or storage backends.

Architecture & Stack

The codebase follows a modular structure: controllers, services, and repositories separate business logic from persistence, enabling straightforward unit testing and future refactors.

Deployment & Infrastructure

• Zero‑config – Launch with docker compose up and the app will auto‑initialize SQLite; no build steps required.
• Scalability – Horizontal scaling is achieved by running multiple API replicas behind a load balancer; shared DB/Redis ensures state consistency.
• Persistence Options – Switching databases only requires updating environment variables; migration scripts are bundled (npm run migrate).
• Resource Footprint – A single container consumes < 100 MiB RAM on a typical web server, making it suitable for VPS or edge deployments.

Integration & Extensibility

• API – Exposes endpoints for creating, updating, and deleting links (POST /api/links, GET /api/links/:id), with optional query parameters for filtering and pagination.
• Webhooks – Configurable via the admin UI; send payloads to external services (e.g., Slack, Datadog).
• OAuth & SSO – Built‑in support for Google/OAuth2; can be extended to other providers via the plugin system.
• Custom Themes – Replace CSS/JS files in /themes or provide a theme package; the engine resolves themes at runtime.
• CLI Tools – A small CLI (kutt-cli) allows bulk import/export of links and users, useful for migrations.

Developer Experience

• Configuration – Environment variables drive behavior (DB_TYPE, REDIS_ENABLED, KUTT_PORT), with a .env.example for reference.
• Documentation – Comprehensive README, API docs generated with Swagger/OpenAPI spec, and inline code comments.
• Community – Active GitHub repository with issue tracking; contributors welcome via pull requests.
• Testing – Jest tests cover controllers and services, ensuring API stability across releases.

Use Cases

Advantages Over Alternatives

Kutt offers a robust, developer‑friendly platform for anyone needing a self‑hosted URL shortener that can grow from simple prototypes to production‑grade services.