Kutt.it

Kutt is a modern URL shortener with support for custom domains. Create and edit links, view statistics, manage users, and more.

https://kutt.it

Table of contents

• Key features
• Donations and sponsors
• Setup
• Docker
• API
• Configuration
• Browser extensions
• Videos
• Integrations
• Contributing

Key features

• Created with self-host in mind:
  • Zero configuration needed
  • Easy setup with no build step
  • Supporting various databases (SQLite, Postgres, MySQL)
  • Ability to disable registration and anonymous links
• Custom domain support
• Set custom URLs, password, description, and expiration time for links
• View, edit, delete and manage your links
• Private statistics for shortened URLs
• Admin page to manage users and links
• RESTful API

Donations and sponsors

Support the development of Kutt by making a donation or becoming an sponsor.

Donate or sponsor →

Setup

The only prerequisite is Node.js (version 20 or above). The default database is SQLite. You can optionally install Posrgres or MySQL/MariaDB for the database or Redis for the cache.

When you first start the app, you're prompted to create an admin account.

1. Clone this repository or download the latest zip
2. Install dependencies: npm install
3. Intialize database: npm run migrate
4. Start the app for development npm run dev or production npm start

Docker

Make sure Docker is installed, then you can start the app from the root directory:

docker compose up

Various docker-compose configurations are available. Use docker compose -f <file_name> up to start the one you want:

• docker-compose.yml: Default Kutt setup. Uses SQLite for the database.
• docker-compose.sqlite-redis.yml: Starts Kutt with SQLite and Redis.
  • Required envrionment variable: REDIS_ENABLED
• docker-compose.postgres.yml: Starts Kutt with Postgres and Redis.
  • Required envrionment variables: REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER
• docker-compose.mariadb.yml: Starts Kutt with MariaDB and Redis.
  • Required envrionment variables: REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER, DB_PORT

Official Kutt Docker image is available on Docker Hub.

API

View API documentation →

Configuration

The app is configured via environment variables. You can pass environment variables directly or create a .env file. View .example.env file for the list of configurations.

All variables are optional except JWT_SECRET which is required on production.

Variable	Description	Default	Example
JWT_SECRET	This is used to sign authentication tokens. Use a long random string.	-	-
PORT	The port to start the app on	3000	8888
SITE_NAME	Name of the website	Kutt	Your Site
DEFAULT_DOMAIN	The domain address that this app runs on	localhost:3000	yoursite.com
LINK_LENGTH	The length of of shortened address	6	5
DISALLOW_REGISTRATION	Disable registration. Note that if MAIL_ENABLED is set to false, then the registration would still be disabled since it relies on emails to sign up users.	true	false
DISALLOW_ANONYMOUS_LINKS	Disable anonymous link creation	true	false
DB_CLIENT	Which database client to use. Supported clients: pg or pg-native for Postgres, mysql2 for MySQL or MariaDB, sqlite3 and better-sqlite3 for SQLite. NOTE: pg-native and better-sqlite3 are not installed by default, use npm to install them before use.	sqlite3	pg
DB_HOST	Database connection host. Only if you use Postgres or MySQL.	localhost	your-db-host.com
DB_PORT	Database port. Only if you use Postgres or MySQL.	5432 (Postgres)	3306 (MySQL)
DB_NAME	Database name. Only if you use Postgres or MySQL.	kutt	mydb
DB_USER	Database user. Only if you use Postgres or MySQL.	postgres	myuser
DB_PASSWORD	Database password. Only if you use Postgres or MySQL.	-	mypassword
DB_SSL	Whether use SSL for the database connection. Only if you use Postgres or MySQL.	false	true
DB_POOL_MIN	Minimum number of database connection pools. Only if you use Postgres or MySQL.	0	2
DB_POOL_MAX	Maximum number of database connection pools. Only if you use Postgres or MySQL.	10	5
REDIS_ENABLED	Whether to use Redis for cache	false	true
REDIS_HOST	Redis connection host	127.0.0.1	your-redis-host.com
REDIS_PORT	Redis port	6379	6379
REDIS_PASSWORD	Redis passowrd	-	mypassword
REDIS_DB	Redis database number, between 0 and 15.	0	1
SERVER_IP_ADDRESS	The IP address shown to the user on the setting's page. It's only for display purposes and has no other use.	-	1.2.3.4
SERVER_CNAME_ADDRESS	The subdomain shown to the user on the setting's page. It's only for display purposes and has no other use.	-	custom.yoursite.com
CUSTOM_DOMAIN_USE_HTTPS	Use https for links with custom domain. It's on you to generate SSL certificates for those domains manually—at least on this version for now.	false	true
ENABLE_RATE_LIMIT	Enable rate limitting for some API routes. If Redis is enabled uses Redis, otherwise, uses memory.	false	true
MAIL_ENABLED	Enable emails, which are used for signup, verifying or changing email address, resetting password, and sending reports. If is disabled, all these functionalities will be disabled too.	false	true
MAIL_HOST	Email server host	-	your-mail-server.com
MAIL_PORT	Email server port	587	465 (SSL)
MAIL_USER	Email server user	-	myuser
MAIL_PASSWORD	Email server password for the user	-	mypassword
MAIL_FROM	Email address to send the user from	-	[email protected]
MAIL_SECURE	Whether use SSL for the email server connection	false	true
REPORT_EMAIL	The email address that will receive submitted reports	-	[email protected]
CONTACT_EMAIL	The support email address to show on the app	-	[email protected]

Browser extensions

Download Kutt's extension for web browsers via below links.

• Chrome
• Firefox

Videos

Official videos

• Next.js to htmx – A Real World Example

Integrations

ShareX

You can use Kutt as your default URL shortener in ShareX. If you host your custom instance of Kutt, refer to ShareX wiki on how to setup.

Alfred workflow

Download Kutt's official workflow for Alfred app from alfred-kutt repository.

Third-party packages

Language	Link	Description
C# (.NET)	KuttSharp	.NET package for Kutt.it url shortener
C# (.NET)	Kutt.NET	C# API Wrapper for Kutt
Python	kutt-cli	Command-line client for Kutt written in Python
Ruby	kutt.rb	Kutt library written in Ruby
Rust	urlshortener	URL shortener library written in Rust
Rust	kutt-rs	Command line tool written in Rust
Node.js	node-kutt	Node.js client for Kutt.it url shortener
JavaScript	kutt-vscode	Visual Studio Code extension for Kutt
Java	kutt-desktop	A Cross platform Java desktop application for Kutt
Go	kutt-go	Go client for Kutt.it url shortener
BASH	GitHub Gist	Simple BASH function to access the API
BASH	url-shortener	Simple BASH script with GUI

Contributing

Pull requests are welcome. Open a discussion for feedback, requesting features, or discussing ideas.

Special thanks to Thomas and Muthu. Logo design by Muthu.