Kutt: The Full Guide to Self-Hosting Anywhere

Kutt is an open-source URL shortener designed for self-hosting, offering a clean API, custom domains, and seamless control over your data. With Kutt, developers and administrators can enjoy a secure, privacy-focused alternative to third-party services while tailoring the app to meet their specific needs. This guide will walk you through installing, configuring, and managing Kutt, covering everything from setting up a reverse proxy to leveraging its unique features.

Installing Kutt

📦 Docker/Docker Compose Setup

Docker is the easiest and most recommended way to deploy Kutt. Below is a docker-compose.yml tailored for Kutt:


version: "3.7"

services:

kutt:

image: kutt/kutt:latest

container_name: kutt

ports:

- "3000:3000"

environment:

PORT: 3000

HOST: "0.0.0.0"

DB_HOST: "mysql"

DB_PORT: 3306

DB_NAME: "kutt_db"

DB_USER: "kutt_user"

DB_PASSWORD: "kutt_password"

DEFAULT_DOMAIN: "example.com"

depends_on:

- db

restart: always

db:

image: mysql:8

container_name: mysql

environment:

MYSQL_ROOT_PASSWORD: "root_password"

MYSQL_DATABASE: "kutt_db"

MYSQL_USER: "kutt_user"

MYSQL_PASSWORD: "kutt_password"

volumes:

- mysql_data:/var/lib/mysql

restart: always

volumes:

mysql_data:

Save the above content in a docker-compose.yml file.
Run the following commands in the same directory:


docker-compose up -d

Access Kutt on http://<server-ip>:3000.

🚀 Manual Installation

For those who prefer manual installation, follow these steps to set up Kutt on a Linux server:

Install Node.js, npm, and MySQL:


sudo apt update && sudo apt install -y nodejs npm mysql-server

Clone the Kutt repository:


git clone https://github.com/thedevs-network/kutt.git

cd kutt

Install dependencies:


npm install

Set up MySQL:


mysql -u root -p -e "

CREATE DATABASE kutt_db;

CREATE USER 'kutt_user'@'localhost' IDENTIFIED BY 'kutt_password';

GRANT ALL PRIVILEGES ON kutt_db.* TO 'kutt_user'@'localhost';

FLUSH PRIVILEGES;"

Create the .env file:


cp .env.example .env

nano .env

Update the database fields and default domain as needed.

Start Kutt:


npm run build

npm start

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Below is an example Nginx server block to proxy requests to Kutt:


server {

server_name example.com;

location / {

proxy_pass http://127.0.0.1:3000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

error_log /var/log/nginx/kutt.error.log;

access_log /var/log/nginx/kutt.access.log;

}

Save this configuration in /etc/nginx/sites-available/kutt and enable it:


sudo ln -s /etc/nginx/sites-available/kutt /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

🔒 SSL/TLS Setup

Use Let's Encrypt to secure your site:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d example.com

Automate certificate renewal:


sudo crontab -e

0 3 * * * certbot renew --quiet

🛠️ Testing and Reloading Nginx

Ensure the configuration is valid and reload Nginx:


sudo nginx -t

sudo systemctl reload nginx

Logging and Debugging Kutt

🗃️ Enabling Debug Logs

To enable debug logs, update the LOG_LEVEL variable in your .env file:


LOG_LEVEL=debug

Restart Kutt to apply changes:


docker-compose restart kutt

📄 Viewing Logs

For Docker users:


docker logs -f kutt

For manual installations:


tail -f logs/*.log

🛠️ Troubleshooting Common Issues

Database Connection Errors: Verify the database credentials in the .env file and ensure MySQL is running.
Port Conflicts: Ensure no other services are using port 3000.

📤 Exporting Logs

Export logs to an external system (e.g., ELK Stack) using filebeat or similar tools. Configure it to read Kutt’s logs from the logs/ directory.

Backup and Restore

🗂️ File-Based Backups

Backup configuration files and .env:


tar -czvf kutt_backup.tar.gz .env docker-compose.yml

🔄 Database Backups

Export the MySQL database:


mysqldump -u kutt_user -p kutt_db > kutt_db_backup.sql

Restore the database:


mysql -u kutt_user -p kutt_db < kutt_db_backup.sql

📅 Automated Backup Scripts

Create a backup script (backup.sh):


#!/bin/bash

mysqldump -u kutt_user -p'kutt_password' kutt_db > /path/to/backups/kutt_db_$(date +%F).sql

tar -czvf /path/to/backups/kutt_$(date +%F).tar.gz /path/to/kutt_config

Set up a cron job:


crontab -e

## Add the following line:

0 2 * * * /path/to/backup.sh

Updating and Upgrading Kutt

⬆️ Updating Docker Images

Pull the latest Kutt image and restart:


docker-compose pull

docker-compose up -d

🛠️ Manual Updates

If installed manually:


git pull origin master

npm install

npm run build

pm2 restart all

🔍 Checking for Updates

Monitor the Kutt GitHub repository for release notes.

Leveraging Kutt’s Unique Features

🔧 Enabling APIs

To enable the API, ensure the DISABLE_API variable in .env is set to false:


DISABLE_API=false

Restart Kutt to apply changes. Test the API using curl:


curl -X POST -H "Content-Type: application/json" -d '{"target": "https://example.com"}' http://example.com/api/url

🌟 Advanced Configurations

Custom Email Notifications: Configure email settings in .env for password resets:


SMTP_HOST=smtp.example.com

SMTP_PORT=587

SMTP_USER=your_user

SMTP_PASSWORD=your_password

Custom Domains: Set DEFAULT_DOMAIN in .env to your desired domain.

Wrapping Up

Self-hosting Kutt empowers you to control your URL shortening service while ensuring privacy and flexibility. By following this guide, you can install and configure Kutt, secure it with SSL, debug issues, and leverage its API for automation. Take full advantage of Kutt’s customizable features to tailor the app to your specific needs. Happy self-hosting!