OpenShort Documentation

Welcome to the OpenShort documentation. OpenShort is a self-hosted, open-source URL shortener built with .NET 9 and Angular 21. It gives you full control over your link infrastructure — deploy it on your own server, use your own domain, and keep your data private.

What is OpenShort?

OpenShort is designed as a privacy-first alternative to commercial URL shorteners like Bitly or TinyURL. Instead of relying on a third-party service that tracks your links and owns your data, OpenShort lets you run the entire system on your own infrastructure.

Key properties:

• Self-hosted — runs entirely on your server or VPS
• Open source — MIT licensed, inspect and modify freely
• Single container — ships as one Docker image with embedded SQLite
• Custom domains — use your own branded short domain
• REST API — integrate link creation into your workflows

Prerequisites

Before installing OpenShort, make sure you have the following:

• Docker (v20.10+) and Docker Compose (v2.0+) installed on your server
• A server or VPS with at least 512 MB RAM (1 GB recommended)
• Ports 80 and 8081 available (or configure alternatives)
• Optional: a custom domain with DNS access for branded short URLs

Installation — Docker Run (Quick Start)

The fastest way to get OpenShort running is with a single docker run command using the public image. No cloning or compose files needed.

SQLite mode (default)

docker run -d \
  --name openshort \
  -p 80:80 \
  -p 8081:8081 \
  -v openshort-data:/app/data \
  --restart unless-stopped \
  ghcr.io/emanueledeamicis/openshort:latest

OpenShort will start with an embedded SQLite database. Data is persisted in the openshort-data Docker volume.

MySQL mode

docker run -d \
  --name openshort \
  -p 80:80 \
  -p 8081:8081 \
  -e MYSQL_HOST=your_mysql_host \
  -e MYSQL_PORT=3306 \
  -e MYSQL_DATABASE=openshort \
  -e MYSQL_USER=openshort \
  -e MYSQL_PASSWORD=your_secure_password \
  --restart unless-stopped \
  ghcr.io/emanueledeamicis/openshort:latest

Installation — Docker Compose with SQLite

For a more structured setup, use Docker Compose with the bundled SQLite database. This requires no external database setup.

Step 1 — Clone the repository

git clone https://github.com/emanueledeamicis/openshort.git
cd openshort

Step 2 — Create your compose file

Create a docker-compose.yml file (or use the one from the repository):

services:
  openshort:
    image: ghcr.io/emanueledeamicis/openshort:latest
    ports:
      - "80:80"
      - "8081:8081"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

Step 3 — Start the service

docker compose up -d

OpenShort will start and automatically initialize the SQLite database. No additional setup required.

Installation — Docker Compose with MySQL

For production deployments or when you need a more scalable database, OpenShort supports MySQL. Configure it via environment variables.

services:
  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: openshort
      MYSQL_USER: openshort
      MYSQL_PASSWORD: yourpassword
    volumes:
      - mysql_data:/var/lib/mysql
    restart: unless-stopped

  openshort:
    image: ghcr.io/emanueledeamicis/openshort:latest
    ports:
      - "80:80"
      - "8081:8081"
    environment:
      MYSQL_HOST: db
      MYSQL_PORT: 3306
      MYSQL_DATABASE: openshort
      MYSQL_USER: openshort
      MYSQL_PASSWORD: yourpassword
    depends_on:
      - db
    restart: unless-stopped

volumes:
  mysql_data:

Ports & Access

You can remap these ports in the Docker Compose file. For example, to use port 3000 for the dashboard:

ports:
  - "443:80"    # HTTPS → redirect API
  - "3000:8081" # Custom port → dashboard

Configuration

OpenShort is configured via environment variables. The following variables are available:

Custom Domains

OpenShort supports custom domains so you can use branded short URLs like go.yourcompany.com/slug instead of your server's IP address.

Setup overview

1. Point your domain's DNS A record to your server's IP address.
2. Set up a reverse proxy (e.g., Nginx or Caddy) to forward traffic to OpenShort's port 80.
3. Configure SSL/TLS for HTTPS (strongly recommended for production).
4. Create short links in the dashboard using your custom domain as the base URL.

Example: Nginx reverse proxy

server {
    listen 80;
    server_name go.yourcompany.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name go.yourcompany.com;

    ssl_certificate     /etc/letsencrypt/live/go.yourcompany.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/go.yourcompany.com/privkey.pem;

    location / {
        proxy_pass         http://localhost:80;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Redirect Types

OpenShort supports two HTTP redirect types, which affect how browsers and search engines handle the redirect.

First Login

On the first startup, OpenShort automatically creates an admin user account. No default credentials are shipped — you set your own password during the initial setup flow.

1. Open the dashboard at http://localhost:8081 (or your configured domain).
2. You'll be prompted to set a password for the admin account.
3. After setting your password, you'll be logged into the dashboard.

Creating Links

You can create short links either via the web dashboard or the REST API.

Via the dashboard

1. Log into the dashboard at port 8081.
2. Click "New Link" or the "+" button.
3. Enter the destination (long) URL.
4. Optionally customize the slug (the short part of the URL). If left blank, a random collision-resistant slug is generated automatically.
5. Choose the redirect type (301 or 302).
6. Click "Create".

Via the API

Generate an API key from the dashboard, then use it in the X-Api-Key header:

curl -X POST http://localhost:80/api/links \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your-api-key-here" \
  -d '{
    "url": "https://example.com/very/long/path?with=params",
    "slug": "my-link",
    "redirectType": 302
  }'

Managing Links

The dashboard provides a full interface for link management:

• List view — see all your short links with their destination URLs and redirect type.
• Edit — update the destination URL, slug, or redirect type of any existing link.
• Delete — permanently remove a link. Deleted links will return a 404 to visitors.
• Copy — quickly copy the short URL to clipboard.

API Reference

OpenShort exposes a REST API on port 80. All management endpoints require an API key passed via the X-Api-Key header. Redirect endpoints are public.