Deploying rs-short

Introduction

rs-short is a lightweight, self-hosted URL shortener written in Rust. Designed for simplicity and performance, rs-short provides essential URL shortening functionality without the bloat of larger solutions. It’s perfect for individuals and organizations who want control over their short links without relying on third-party services.

Built with Rust’s focus on performance and safety, rs-short handles link creation and redirection with minimal resource usage. The application uses SQLite for storage, making it easy to deploy and maintain without external database dependencies.

Key highlights of rs-short:

• Fast Performance: Written in Rust for minimal latency redirects
• Simple API: Clean REST API for creating and managing short links
• SQLite Storage: No external database required
• Custom Slugs: Choose your own short URL paths
• Statistics Tracking: Basic click tracking and analytics
• Low Resource Usage: Runs efficiently on minimal hardware
• Easy Deployment: Single binary with embedded database
• Privacy-Respecting: No third-party tracking or analytics
• Self-Hosted: Complete control over your data and links
• Open Source: Freely available for modification and self-hosting

This guide walks through deploying rs-short on Klutch.sh using Docker, configuring the URL shortener, and setting up the application for production use.

Why Deploy rs-short on Klutch.sh

Deploying rs-short on Klutch.sh provides several advantages for URL shortening:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds rs-short without complex orchestration. Push to GitHub, and your URL shortener deploys automatically.

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 a trusted URL shortener service.

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

Custom Domains: Use a custom short domain for branded, memorable links.

Scalable Resources: rs-short is extremely lightweight, but you can scale as needed for high traffic.

Always-On Availability: Your URL shortener runs 24/7, ensuring short links always resolve.

Prerequisites

Before deploying rs-short on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your rs-short configuration
• Basic familiarity with Docker and REST APIs
• (Optional) A short custom domain for your links

Understanding rs-short Architecture

rs-short is built for simplicity:

Rust Binary: A single compiled binary handles HTTP requests, database operations, and URL redirection.

SQLite Database: All link data is stored in a SQLite file, eliminating external dependencies.

Actix Web: Uses the high-performance Actix web framework for handling HTTP requests.

Stateless Design: Each request is handled independently, making scaling straightforward.

Preparing Your Repository

To deploy rs-short on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

rs-short-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM rust:1.75-alpine AS builder

# Install build dependencies
RUN apk add --no-cache musl-dev sqlite-dev

# Clone and build rs-short
WORKDIR /build
RUN apk add --no-cache git && \
    git clone https://github.com/your-source/rs-short.git . && \
    cargo build --release

FROM alpine:latest

# Install runtime dependencies
RUN apk add --no-cache sqlite-libs

# Copy the binary
COPY --from=builder /build/target/release/rs-short /usr/local/bin/rs-short

# Create data directory
RUN mkdir -p /data

# Environment variables
ENV DATABASE_PATH=/data/urls.db
ENV HOST=0.0.0.0
ENV PORT=8080

# Expose the web port
EXPOSE 8080

CMD ["rs-short"]

Alternative Dockerfile Using Pre-built Image

If a Docker image is available:

FROM your-registry/rs-short:latest

# Environment configuration
ENV DATABASE_PATH=/data/urls.db
ENV HOST=0.0.0.0
ENV PORT=8080
ENV BASE_URL=https://your-short-domain.com

# Create data directory
RUN mkdir -p /data

EXPOSE 8080

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
target/

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_PATH	No	./urls.db	Path to SQLite database
HOST	No	0.0.0.0	Bind address
PORT	No	8080	Listen port
BASE_URL	Yes	-	Base URL for generated short links
API_KEY	No	-	API key for authenticated operations

Deploying rs-short on Klutch.sh

Once your repository is prepared, follow these steps to deploy rs-short:

Generate an API Key

Generate a secure API key for creating short links:

openssl rand -hex 32

Save this key for API authentication.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial rs-short deployment configuration"
git remote add origin https://github.com/yourusername/rs-short-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 “url-shortener” or “short-links”.

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 rs-short Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
DATABASE_PATH	/data/urls.db
HOST	0.0.0.0
PORT	8080
BASE_URL	https://your-app-name.klutch.sh
API_KEY	Your generated API key

Attach Persistent Volumes

Add the following volume for data persistence:

Mount Path	Recommended Size	Purpose
/data	1 GB	SQLite database for short links

Configure Custom Domain (Optional)

For a short, branded domain:

1. Add your custom domain in Klutch.sh settings
2. Update DNS records as instructed
3. Update BASE_URL environment variable

Deploy Your Application

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

• Build the rs-short binary
• Attach the persistent volumes
• Start the container
• Provision an HTTPS certificate

Access rs-short

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

Using rs-short

Creating Short Links via API

Create a short link using curl:

curl -X POST https://your-short-domain.klutch.sh/api/shorten \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very-long-url-here"}'

Response:

{
  "short_url": "https://your-short-domain.klutch.sh/abc123",
  "original_url": "https://example.com/very-long-url-here",
  "slug": "abc123"
}

Custom Slugs

Specify your own short URL path:

curl -X POST https://your-short-domain.klutch.sh/api/shorten \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/page", "slug": "my-custom-slug"}'

Viewing Statistics

Get click statistics for a short link:

curl https://your-short-domain.klutch.sh/api/stats/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Deleting Links

Remove a short link:

curl -X DELETE https://your-short-domain.klutch.sh/api/links/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Production Best Practices

Security Recommendations

• API Key Protection: Keep your API key secure and rotate periodically
• HTTPS Only: Always use HTTPS (provided by Klutch.sh)
• Rate Limiting: Consider implementing rate limits for public access
• Input Validation: The application validates URLs, but review settings

Performance Optimization

• SQLite Settings: Default settings work well for most use cases
• Caching: Consider a CDN for high-traffic deployments
• Monitoring: Track redirect latency and error rates

Backup Strategy

1. Database Backup: Regularly back up the SQLite database file
2. Export Links: Periodically export all links for disaster recovery

Troubleshooting Common Issues

Short Links Not Redirecting

Symptoms: Visiting a short URL returns an error.

Solutions:

• Verify the link exists in the database
• Check BASE_URL is correctly configured
• Ensure the original URL is still valid

API Authentication Failing

Symptoms: API requests return 401 Unauthorized.

Solutions:

• Verify API key is correct
• Check Authorization header format
• Ensure API key environment variable is set

Database Errors

Symptoms: Application fails with database errors.

Solutions:

• Verify volume is properly mounted
• Check file permissions
• Ensure sufficient disk space

Additional Resources

• Klutch.sh Persistent Volumes
• Klutch.sh Deployments
• Klutch.sh Custom Domains

Conclusion

Deploying rs-short on Klutch.sh gives you a fast, self-hosted URL shortener with automatic builds, persistent storage, and secure HTTPS access. The combination of Rust’s performance and Klutch.sh’s deployment simplicity means you can run a reliable link shortening service with minimal overhead.

With API access, custom slugs, and click tracking, rs-short provides the essential features for URL shortening while respecting privacy. The lightweight architecture means fast redirects and efficient resource usage.

Whether you’re shortening links for personal use or running a service for your organization, rs-short on Klutch.sh provides the reliable foundation for self-hosted URL management.