kutt README

The project's README from github.com/thedevs-network/kutt. As one markdown file: README.md.

Kutt.to

Kutt.to

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

https://kutt.to

[!WARNING] kutt.it is NOT OWNED BY US. It could be a phishing site. We had the domain but it has been deactivated by the Italian TLD registrar due to the lack of identification documents, and now it's owned by someone else.

Please use kutt.to, all the previous and the future links work with this domain as well.

docker-build-release Uptime Status Contributions GitHub license

Table of contents

Key features

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:

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.

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
LINK_CUSTOM_ALPHABET Alphabet used to generate custom addresses. Default value omits o, O, 0, i, I, l, 1, and j to avoid confusion when reading the URL. (abcd..789) abcABC^&*()@
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_LOGIN_FORM Disable login with email and password. Only makes sense if OIDC is enabled. false true
DISALLOW_ANONYMOUS_LINKS Disable anonymous link creation true false
TRUST_PROXY If the app is running behind a proxy server like NGINX or Cloudflare and that it should get the IP address from that proxy server. If you're not using a proxy server then set this to false, otherwise users can override their IP address. 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 sqlite3 are not installed by default, use npm to install them before use. better-sqlite3 pg
DB_FILENAME File path for the SQLite database. Only if you use SQLite. db/data /var/lib/data
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 password - 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 limiting 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
OIDC_ENABLED Enable OpenID Connect false true
OIDC_ISSUER OIDC issuer URL - https://example.com/some/path
OIDC_POMPT OIDC prompt - login
OIDC_CLIENT_ID OIDC client id - example-app
OIDC_CLIENT_SECRET OIDC client secret - some-secret
OIDC_SCOPE OIDC Scope openid profile email openid email
OIDC_EMAIL_CLAIM Name of the field to get user's email from email userEmail
OIDC_BUTTON_TEXT OIDC login button text Log in with OIDC Log in via Example
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]

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
│  ├─ ...

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
crimson-homepage crimson-admin crimson-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.

Videos

Official videos

Integrations

Third-party packages

Language Link Description
C# (.NET) KuttSharp .NET package for Kutt.to 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.to 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.to url shortener
BASH GitHub Gist Simple BASH function to access the API
BASH url-shortener Simple BASH script with GUI
Kubernetes/Helm ArtifactHub A Helm Chart to install Kutt on a Kubernetes cluster

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.

kutt (thedevs-network/kutt)

Searching Database…

11.2K ·GitHub
Kutt
这是什么东西？Kutt 是一个免费开源、可以自己部署的短链接服务：它能在自定义域名上缩短链接，为每条链接保留私密的访问统计，还带有管理面板和 RESTful API。
这是托管服务，还是要我自己运行的？这是一个自托管的网络服务：一个 Node.js 应用，部署在你自己的服务器上，在浏览器里使用。你还可以把自定义的 CSS、图片和 HTML 模板放进 /custom 文件夹来自定义界面外观。
怎么把它跑起来？先安装 Node.js 20+，然后在克隆下来的仓库里依次运行 npm install、npm run migrate 和 npm start（开发时用 npm run dev）。首次启动时会提示你创建一个管理员账号。
我需要为它配置数据库或其他服务吗？不需要，默认使用 SQLite，开箱即用。Postgres、MySQL/MariaDB，以及用于缓存的 Redis 都是可选的，通过环境变量来选择。
正式投入使用前我该注意什么？两点：JWTSECRET 是生产环境中唯一必填的配置（请用一个较长的随机字符串），另外在当前版本中，自定义域名要启用 HTTPS 就得自己生成 SSL 证书。
kutt.it 还是这个项目的官方网站吗？不是。团队失去了那个域名，现在归别人所有，因此那可能是一个钓鱼网站——请使用 kutt.to，新旧链接在那里都能正常跳转。
我创建的每条短链接可以控制哪些内容？你可以为短链接设置自定义网址、密码、描述和过期时间，之后还能查看、编辑、删除链接，并查看它们的私密统计。
我能限制实例，只允许特定的人创建链接吗？可以——你可以关闭注册和匿名创建链接，添加 OpenID Connect（OIDC）登录，并在管理页面里管理用户和链接。
有 API 吗？有没有现成的客户端？有 RESTful API，还有官方的 Chrome 和 Firefox 扩展，以及 Python、Go、Rust、C#、Ruby、Node.js 和 Java 的社区客户端——其中包括一个 VS Code 扩展和一个 Helm chart。
What are similar projects?YOURLS, casdoor, directus, Termix, taskview-community, rankme.fast, new-api, remix
Which topics is it in?htmx, url-shortener, oidc, express, browser-extension, mysql, redis, sqlite, postgresql, docker-compose, rest-api, api
Creator
thedevs-network
Size
5.3 MB
Stars
11.2K
Updated
CommitSep 03Releasev3.2.6Jul 05
Age
8y
Commits · 90 Days