Quick Start

This guide helps you configure and use Shortlinker in 5 minutes.

Prerequisites

Please complete any installation method from the Installation Guide first.

Step 1: Basic Configuration

Method 1: Using TOML Configuration File (Recommended)

Use the generate-config command to generate a configuration file:

./shortlinker generate-config
# Generates config.toml with all configurable options and default values

Then modify config.toml as needed:

[server]
host = "127.0.0.1"
port = 8080

[features]
default_url = "https://example.com"

# Optional: Enable admin features (Admin API + Health API)
# - Health supports Bearer token auth (HEALTH_TOKEN) or Admin JWT cookies
# [api]
# admin_token = "your_admin_token"

TIP

If you don't create a configuration file, the program will run with built-in default settings.

Method 2: Using Environment Variables

Create configuration file .env:

# Minimal configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8080
DEFAULT_URL=https://example.com

# Optional: Enable admin features (Admin API + Health API)
# - Health supports Bearer token auth (HEALTH_TOKEN) or Admin JWT cookies
# ADMIN_TOKEN=your_admin_token

Step 2: Start Service

# Start server
./shortlinker

# Success output:
# [INFO] Starting server at http://127.0.0.1:8080
# [INFO] SQLite storage initialized with 0 links

Step 3: Add Short Links

# Custom short code
./shortlinker add github https://github.com

# Random short code
./shortlinker add https://www.google.com
# Output: ✓ Added short link: aB3dF1 -> https://www.google.com

Step 4: Test Access

# Test redirect
curl -I http://localhost:8080/github
# HTTP/1.1 307 Temporary Redirect
# Location: https://github.com

# Browser access
# http://localhost:8080/github

Common Operations

# View all short links
./shortlinker list

# Delete short link
./shortlinker remove github

# Add temporary link
./shortlinker add temp https://example.com --expire 1d

# Force overwrite
./shortlinker add github https://github.com --force

Service Management

# Stop service
# Method 1: Ctrl+C
# Method 2: Send signal
kill $(cat shortlinker.pid)

# Reload short link data / caches (Unix systems)
# Note: SIGUSR1 only reloads link data/caches; it does NOT reload runtime config.
# Reload runtime config via Admin API `/admin/v1/config/reload` or restart the service.
kill -USR1 $(cat shortlinker.pid)

Production Environment Quick Configuration

Recommended Configuration

# Production .env configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8080
DATABASE_URL=sqlite:///data/links.db
DEFAULT_URL=https://your-domain.com

# Enable API features
ADMIN_TOKEN=your_secure_admin_token

Reverse Proxy Example

# Nginx configuration example
server {
    listen 80;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
    }
}

Docker Quick Deployment

# Using Docker Compose
version: '3.8'
services:
  shortlinker:
    image: e1saps/shortlinker
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./data:/data
    environment:
      - DATABASE_URL=sqlite:///data/links.db

Next Steps

Congratulations! You have successfully configured Shortlinker. Next you can:

• 📋 Learn CLI Command Details - Master all command options
• 🚀 Check Deployment Guide - Production environment deployment
• ⚙️ Learn Configuration Options - Customize advanced settings
• 🛡️ Use Admin API - HTTP interface management
• 🏥 Configure Health Check - Service monitoring