kutt/kutt repository overview

⁠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⁠
• Themes and customizations⁠
• 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
  • OpenID Connect (OIDC) login
• 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
• Customizability and themes
• 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 Postgres 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. Initialize 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 environment variable: REDIS_ENABLED
• docker-compose.postgres.yml⁠: Starts Kutt with Postgres and Redis.
  • Required environment variables: REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER
• docker-compose.mariadb.yml⁠: Starts Kutt with MariaDB and Redis.
  • Required environment 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.

You can use files for each of the variables by appending _FILE to the name of the variable. Example: JWT_SECRET_FILE=/path/to/secret_file.

⁠Themes and customizations

You can add styles, change images, or render custom HTML. Place your content inside the /custom⁠ folder according to below instructions.

⁠How it works:

The structure of the custom folder is like this:

custom/
├─ css/
│  ├─ custom1.css
│  ├─ custom2.css
│  ├─ ...
├─ images/
│  ├─ logo.png
│  ├─ favicon.ico
│  ├─ ...
├─ views/
│  ├─ partials/
│  │  ├─ footer.hbs
│  ├─ 404.hbs
│  ├─ ...

• css: Put your CSS style files here. (View example →⁠)
  • You can put as many style files as you want: custom1.css, custom2.css, etc.
  • If you name your style file styles.css, it will replace Kutt's original styles.css file.
  • Each file will be accessible by <your-site.com>/css/<file>.css
• images: Put your images here. (View example →⁠)
  • Name them just like the files inside the /static/images/⁠ folder to replace Kutt's original images.
  • Each image will be accessible by <your-site.com>/images/<image>.<image-format>
• views: Custom HTML templates to render. (View example →⁠)
  • It should follow the same file naming and folder structure as /server/views⁠
  • Although we try to keep the original file names unchanged, be aware that new changes on Kutt might break your custom views.

⁠Example theme: Crimson

This is an example and official theme. Crimson includes custom styles, images, and views.

Get Crimson theme →⁠

View list of themes and customizations →⁠

Homepage	Admin page	Login/signup

⁠Usage with Docker:

If you're building the image locally, then the /custom folder should already be included in your app.

If you're pulling the official image, make sure /kutt/custom volume is mounted or you have access to it. View Docker compose example →⁠

Then, move your files to that volume. You can do it with this Docker command:

docker cp <path-to-custom-folder> <kutt-container-name>:/kutt

For example:

docker cp custom kutt-server-1:/kutt

Make sure to restart the kutt server container after copying files or making changes.

⁠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.
• iOS shortcut – Kutt shortcut⁠ for your apple device which works from the iOS sharing context menu or on standalone mode. A courtesy of @caneeeeee⁠.

Third-party packages

⁠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⁠.