Self-Hosted URL Shortener Setup

Launch your own privacy-first URL shortener in minutes. Whether you choose Docker or a native install, you’ll have a fast, lightweight service running on your own server—no third parties required.

Why Choose a Self-Hosted URL Shortener?

Full Control & Privacy Host on your own VPS, Kubernetes, Docker, Cloudflare Workers or local machine—no vendor lock-in, no data leaks.
Fast & Lightweight Built on Node.js with minimal dependencies for rock-solid performance.

🚀 Quickstart: Docker Setup

Install Docker Get Docker Desktop for Windows/macOS or install Docker Engine on Linux from docker.com.
Run the Container
```
docker run -d 
  -p 3001:3001 
  --name my-shrtn 
  -v ~/shrtn-data:/data 
  -e ORIGIN=https://url.example.com 
  cordlesswool/shrtn
```
- ORIGIN: The public URL where your short URLs resolve (e.g. https://url.example.com).
- MAIL_FROM: Sender address for notification emails.
  
  Do NOT set DATABASE_URL! It’s already configured within the Docker container, and modifying it may lead to issues.
Verify & Use Open https://url.example.com in your browser to start creating and managing short URLs instantly.
Configure your email provider for login; all necessary environment variables are detailed below.

⚙️ Native Install (No Docker)

Download & Extract Grab the latest release from the GitHub Releases page.

Install Dependencies

cd shrtn
bun install --production
bun run db:migrate

Configure Environment Create a .env file in the project root:

DATABASE_URL=file:./shrtn.sqlite
ORIGIN=https://URLs.example.com
MAIL_PROVIDER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=465
MAIL_USER=user@example.com
MAIL_PASS=strong_password
MAIL_FROM=noreply@example.com
PUBLIC_TTL_TEMP=DAY
PUBLIC_TTL_USER=YEAR

Start the Service
```
node index.js
```
Setup Cron to Cleanup If you want to automatically clean up expired URLs, add the following to your crontab:
```
0 0 * * * http://localhost:3000/cleanup
```

🛠️ Upcoming Features (Roadmap)

We’re actively working on:

On-Prem Analytics Dashboard View click-through trends, top referrers, and geodata stored on your server.
Developer-Friendly A simple, RESTful API and minimal dependencies mean quick integrations and rock-solid stability.

🔧 Environment Variables & Customization

Don’t be confused about the PUBLIC_prefix. It is used to indicate that the variable is public and can be accessed on the browser. This means all other variables are protected by default.

Base Configuration

Variable	Description	Default
`PUBLIC_FEATURE_PRIVATE_LINKS`	Enable private access to your URL shortener instance. `on` \| `off`	`off`
`PUBLIC_INSTANCE_MODE`	Allow only or disable public access to your URL shortener instance. `PUBLIC_ONLY` \| `PRIVATE`	-
`DATABASE_URL`	Connection string (SQLite, Tursor)	–
`ORIGIN`	Base URL for your URL shortener instance.	–
`MAIL_PROVIDER`	`smtp` \| `mailgun` \| `mailpit` (see below)	–
`PUBLIC_TTL_TEMP`	Default expiry for anonymous/temporary users `HOUR` `DAY` `WEEK` `MONTH` `YEAR`	–
`PUBLIC_TTL_USER`	Default expiry for authenticated users `HOUR` `DAY` `WEEK` `MONTH` `YEAR`	–
`ALLOWED_LOGIN_EMAILS`	List of email addresses that are allowed to login to your account. Use `;` as a separator. Will disable `ALLOWED_LOGIN_DOMAINS`.	–
`ALLOWED_LOGIN_DOMAINS`	List of email domains that are allowed to login to your account. Use `;` as a separator.	–

Sending Emails

To login to your account or even create a new one, you need to setup a email provider. Choose one of the following providers:

Mailpit

Set MAIL_PROVIDER to MAILPIT

Variable	Description	Default
`MAILPIT_DOMAIN`	URL to your Mailpit Server (e.g. `https://my.mailpit.io`)	—
`MAIL_FROM`	Envelope “from” address for outgoing mail	`noreply@example.com`

Postmark

Set MAIL_PROVIDER to POSTMARK

Variable	Description	Default
`POSTMARK_API_TOKEN`	API token for your Postmark account	—
`POSTMARK_STREAM`	Name of your Postmark message stream	—
`MAIL_FROM`	Envelope “from” address for outgoing mail	`noreply@example.com`

Mailgun

Set MAIL_PROVIDER to MAILGUN

Variable	Description	Default
`MAILGUN_DOMAIN`	Domain of your Mailgun account (e.g. `mg.example.com`)	—
`MAILGUN_API_KEY`	API key for your Mailgun account	—
`MAILGUN_URL`	URL of Mailgun ( e.g. `https://api.mailgun.net`)	—
`MAIL_FROM`	Envelope “from” address for outgoing mail	`noreply@example.com`

SMTP

Set MAIL_PROVIDER to SMTP.

Variable	Description	Default
`MAIL_HOST`	SMTP host for sending emails	—
`MAIL_PORT`	SMTP port	—
`MAIL_USER`	SMTP username	—
`MAIL_PASS`	SMTP password	—
`MAIL_FROM`	Envelope “from” address for outgoing mail	`noreply@example.com`

📦 Supported Databases & Deploy Targets

SQLite (default) - via libSQL
Tursor (default) - via libSQL
Cloudflare D1 for edge-deployed, serverless URL hosting
Deploy via Docker, Kubernetes, Cloudflare Worker, Cloud VM or bare-metal

Questions or Feedback?

Join us on GitHub Discussions or open an issue—happy to help!