Deploying Kutt

Introduction

Kutt is a modern, open source URL shortener that allows you to create short links with custom domains, detailed analytics, and a powerful API. Built with Node.js and React, Kutt provides a clean, fast interface for managing your shortened URLs while maintaining full control over your data.

Unlike commercial URL shorteners, Kutt gives you complete ownership of your links and analytics data. You can use your own domain, track clicks with detailed statistics, and integrate with your applications through the REST API.

Key features of Kutt:

• Custom Domains: Use your own short domain for branded links
• Link Analytics: Track clicks, browsers, operating systems, and countries
• Password Protection: Secure links with passwords
• Link Expiration: Set expiration dates for temporary links
• Custom Slugs: Create memorable custom short URLs
• API Access: Full REST API for integration and automation
• QR Codes: Generate QR codes for any short link
• Browser Extensions: Quick shortening from Chrome and Firefox
• Link Editing: Update destination URLs without changing the short link
• User Management: Multi-user support with registration controls
• Rate Limiting: Protect against abuse
• Open Source: MIT licensed and actively maintained

This guide walks through deploying Kutt on Klutch.sh using Docker, configuring your custom domain, and setting up analytics tracking.

Why Deploy Kutt on Klutch.sh

Deploying Kutt on Klutch.sh provides several advantages for URL shortening:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kutt without complex orchestration.

Persistent Storage: Attach persistent volumes for your link database. Your short links survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure link redirection.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your traffic volume.

Environment Variable Management: Securely store database credentials and API keys.

Custom Domains: Essential for branded short URLs with your own domain.

Always-On Availability: Your short links work 24/7 without downtime.

Prerequisites

Before deploying Kutt on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and Node.js
• A PostgreSQL database
• A Redis instance
• (Optional) A short custom domain for branded links

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Kutt on Klutch.sh.

Repository Structure

kutt-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Install dependencies
RUN apk add --no-cache git

# Set working directory
WORKDIR /app

# Clone Kutt
RUN git clone https://github.com/thedevs-network/kutt.git .

# Install dependencies
RUN npm install

# Build the application
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Expose port
EXPOSE 3000

# Start the application
CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Default	Description
PORT	No	3000	Port for the web interface
SITE_NAME	No	Kutt	Name displayed in the UI
DEFAULT_DOMAIN	Yes	-	Your short link domain
LINK_LENGTH	No	6	Length of generated short URLs
DB_HOST	Yes	-	PostgreSQL host
DB_PORT	No	5432	PostgreSQL port
DB_NAME	Yes	-	PostgreSQL database name
DB_USER	Yes	-	PostgreSQL username
DB_PASSWORD	Yes	-	PostgreSQL password
REDIS_HOST	Yes	-	Redis host
REDIS_PORT	No	6379	Redis port
REDIS_PASSWORD	No	-	Redis password
JWT_SECRET	Yes	-	Secret for JWT tokens
MAIL_HOST	No	-	SMTP host for emails
MAIL_PORT	No	-	SMTP port
MAIL_USER	No	-	SMTP username
MAIL_PASSWORD	No	-	SMTP password
MAIL_FROM	No	-	From address for emails
REPORT_EMAIL	No	-	Email for abuse reports
DISALLOW_REGISTRATION	No	false	Disable new registrations
DISALLOW_ANONYMOUS_LINKS	No	false	Require login to create links

Deploying Kutt on Klutch.sh

Generate a JWT Secret

Generate a secure JWT secret:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Kutt deployment configuration"
git remote add origin https://github.com/yourusername/kutt-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kutt” or “url-shortener”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kutt Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
DEFAULT_DOMAIN	Your short link domain
DB_HOST	Your PostgreSQL host
DB_NAME	Your database name
DB_USER	Your database user
DB_PASSWORD	Your database password
REDIS_HOST	Your Redis host
JWT_SECRET	Your generated JWT secret
NODE_ENV	production

Attach Persistent Volumes

Kutt uses PostgreSQL and Redis for data storage, so volumes are optional. For logs:

Mount Path	Recommended Size	Purpose
/app/logs	2 GB	Application logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Kutt container
• Provision an HTTPS certificate

Run Database Migrations

After deployment, run migrations:

npm run db:migrate

Access Kutt

Once deployment completes, access your Kutt instance at https://your-app-name.klutch.sh.

Initial Configuration

Creating Your Account

When you first access Kutt:

1. Click Sign Up
2. Enter your email and password
3. Verify your email (if SMTP configured)
4. Log in to access the dashboard

Creating Short Links

Create your first short URL:

1. Click New Link
2. Enter the destination URL
3. Optionally set a custom slug
4. Add password or expiration if needed
5. Click Shorten

Setting Up Custom Domains

To use your own short domain:

1. Point your domain’s DNS to your Kutt instance
2. Configure Klutch.sh custom domain settings
3. Update DEFAULT_DOMAIN environment variable
4. Restart the application

API Usage

API Authentication

Get your API key from Settings to use the API:

curl -X POST https://your-kutt-domain/api/v2/links \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"target": "https://example.com", "description": "Example link"}'

Common API Endpoints

Method	Endpoint	Description
POST	/api/v2/links	Create a new short link
GET	/api/v2/links	List your links
DELETE	/api/v2/links/:id	Delete a link
GET	/api/v2/links/:id/stats	Get link statistics

Troubleshooting Common Issues

Database Connection Errors

• Verify PostgreSQL credentials
• Check network connectivity
• Ensure database exists

Redis Connection Errors

• Verify Redis host and port
• Check Redis password if set
• Ensure Redis is running

Links Not Redirecting

• Verify DEFAULT_DOMAIN matches your domain
• Check DNS configuration
• Review nginx/proxy settings

Additional Resources

• Official Kutt Website
• Kutt GitHub Repository
• Kutt Documentation

Conclusion

Deploying Kutt on Klutch.sh gives you a powerful, self-hosted URL shortener with custom domains, analytics, and API access. Create branded short links without relying on third-party services.