base on Free Modern URL Shortener. <p align="center"><a href="https://kutt.it" title="kutt.it"><img src="https://raw.githubusercontent.com/thedevs-network/kutt/9d1c873897c3f5b9a1bd0c74dc5d23f2ed01f2ec/static/images/logo-github.png" alt="Kutt.it"></a></p> # 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](https://kutt.it) [](https://github.com/thedevs-network/kutt/actions/workflows/docker-build-release.yaml) [](https://status.kutt.it) [](https://github.com/thedevs-network/kutt/#contributing) [](https://github.com/thedevs-network/kutt/blob/develop/LICENSE) ## Table of contents - [Key features](#key-features) - [Donations and sponsors](#donations-and-sponsors) - [Setup](#setup) - [Docker](#docker) - [API](#api) - [Configuration](#configuration) - [Themes and customizations](#themes-and-customizations) - [Browser extensions](#browser-extensions) - [Videos](#videos) - [Integrations](#integrations) - [Contributing](#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 →](https://btcpay.kutt.it/apps/L9Gc7PrnLykeRHkhsH2jHivBeEh/crowdfund) ## Setup The only prerequisite is [Node.js](https://nodejs.org/) (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](https://github.com/thedevs-network/kutt/releases) 2. Install dependencies: `npm install` 3. Initialize database: `npm run migrate` 5. 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: ```sh 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`](./docker-compose.yml): Default Kutt setup. Uses SQLite for the database. - [`docker-compose.sqlite-redis.yml`](./docker-compose.sqlite-redis.yml): Starts Kutt with SQLite and Redis. - Required environment variable: `REDIS_ENABLED` - [`docker-compose.postgres.yml`](./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`](./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](https://hub.docker.com/r/kutt/kutt). ## API [View API documentation →](https://docs.kutt.it) ## Configuration The app is configured via environment variables. You can pass environment variables directly or create a `.env` file. View [`.example.env`](./.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_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` | | `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`](./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 →](https://github.com/thedevs-network/kutt-customizations/tree/main/themes/crimson/css)) - 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 →](https://github.com/thedevs-network/kutt-customizations/tree/main/themes/crimson/images)) - Name them just like the files inside the [`/static/images/`](./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 →](https://github.com/thedevs-network/kutt-customizations/tree/main/themes/crimson/views)) - It should follow the same file naming and folder structure as [`/server/views`](./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 →](https://github.com/thedevs-network/kutt-customizations/tree/main/themes/crimson) [View list of themes and customizations →](https://github.com/thedevs-network/kutt-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 →](https://github.com/thedevs-network/kutt/blob/main/docker-compose.yml#L7) Then, move your files to that volume. You can do it with this Docker command: ```sh docker cp <path-to-custom-folder> <kutt-container-name>:/kutt ``` For example: ```sh 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](https://chrome.google.com/webstore/detail/kutt/pklakpjfiegjacoppcodencchehlfnpd) - [Firefox](https://addons.mozilla.org/en-US/firefox/addon/kutt/) ## Videos **Official videos** - [Next.js to htmx – A Real World Example](https://www.youtube.com/watch?v=8RL4NvYZDT4) ## Integrations - **ShareX** – You can use Kutt as your default URL shortener in [ShareX](https://getsharex.com/). If you host your custom instance of Kutt, refer to [ShareX wiki](https://github.com/thedevs-network/kutt/wiki/ShareX) on how to setup. - **Alfred workflow** – Download Kutt's official workflow for [Alfred](https://www.alfredapp.com/) app from [alfred-kutt](https://github.com/thedevs-network/alfred-kutt) repository. - **iOS shortcut** – [Kutt shortcut](https://www.icloud.com/shortcuts/a829856aea2c420e97c53437e68b752b) for your apple device which works from the iOS sharing context menu or on standalone mode. A courtesy of [@caneeeeee](https://github.com/caneeeeee). **Third-party packages** | Language | Link | Description | | --------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- | | C# (.NET) | [KuttSharp](https://github.com/0xaryan/KuttSharp) | .NET package for Kutt.it url shortener | | C# (.NET) | [Kutt.NET](https://github.com/AlphaNecron/Kutt.NET) | C# API Wrapper for Kutt | | Python | [kutt-cli](https://github.com/RealAmirali/kutt-cli) | Command-line client for Kutt written in Python | | Ruby | [kutt.rb](https://github.com/RealAmirali/kutt.rb) | Kutt library written in Ruby | | Rust | [urlshortener](https://github.com/vityafx/urlshortener-rs) | URL shortener library written in Rust | | Rust | [kutt-rs](https://github.com/robatipoor/kutt-rs) | Command line tool written in Rust | | Node.js | [node-kutt](https://github.com/ardalanamini/node-kutt) | Node.js client for Kutt.it url shortener | | JavaScript | [kutt-vscode](https://github.com/mehrad77/kutt-vscode) | Visual Studio Code extension for Kutt | | Java | [kutt-desktop](https://github.com/cipher812/kutt-desktop) | A Cross platform Java desktop application for Kutt | | Go | [kutt-go](https://github.com/raahii/kutt-go) | Go client for Kutt.it url shortener | | BASH | [GitHub Gist](https://gist.github.com/hashworks/6d6e4eae8984a5018f7692a796d570b4) | Simple BASH function to access the API | | BASH | [url-shortener](https://git.tim-peters.org/Tim/url-shortener) | Simple BASH script with GUI | | Kubernetes/Helm | [ArtifactHub](https://artifacthub.io/packages/helm/christianhuth/kutt) | 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](https://github.com/trgwii) and [Muthu](https://github.com/MKRhere). Logo design by [Muthu](https://github.com/MKRhere). ", Assign "at most 3 tags" to the expected json: {"id":"12389","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"