shortener

shortener is a small URL shortener written in Rust. It serves HTTP redirects, stores mappings in SQLite, and optionally protects URL creation with API keys. The repository also includes shortenerkey, a companion CLI for managing users and API keys.

Features

Plain HTTP interface with no frontend dependency.
SQLite-backed URL storage.
Random alphanumeric codes with configurable length.
Custom aliases using letters, digits, dashes (-), and underscores (_).
Optional bearer-token authentication for URL creation.
User and API key management through shortenerkey.
Access logging to stdout and a log file.
Reverse-proxy support through --trust-proxy.
Optional redirect from / to a configured main page.

Installation

All installation methods come with two executables:

shortener: the HTTP server.
shortenerkey: the user and API key management CLI.

Homebrew

shortener can be installed on macOS and Linux with Homebrew:

brew install zhongruoyu/tap/shortener

Release binaries

shortener's GitHub releases come with pre-built binaries for Linux, macOS, and Windows. Download the binaries from the latest release.

Cargo

Install shortener with Cargo as follows:

cargo install --locked --git https://github.com/ZhongRuoyu/shortener.git

By default, shortener uses the system's SQLite library. If you don't have it installed, or want to use the bundled version, add --features bundled-sqlite to the cargo install command.

Docker

A Docker image is available on Docker Hub as zhongruoyu/shortener, and on GitHub Container Registry as ghcr.io/zhongruoyu/shortener. Use the latest tag or a specific version tag like v0.1.0 to track releases, and main to track the latest commit on the main branch.

See "Run with Docker" for usage instructions with Docker.

Usage

Starting the server

Start a local instance:

shortener \
  --listen-port 8080 \
  --url-prefix http://localhost:8080/ \
  --sqlite-db shortener.db \
  --log-file access.log

Useful flags:

--auth: require Authorization: Bearer ... for POST requests.
--main-page URL: redirect / to a separate landing page.
--code-length N: change generated code length. The default is 6.
--trust-proxy: use the first X-Forwarded-For address for logging.

See the full CLI help with:

shortener --help
shortenerkey --help

Creating and using short URLs

Create a short URL by sending the target URL as the plain-text request body:

curl -X POST http://localhost:8080/ -d 'https://example.com/some/long/path'

The response is the new shortened URL as plain text.

Create a custom alias by posting to /<code>:

curl -X POST http://localhost:8080/docs -d 'https://example.com/docs'

Open the generated short URL and the server returns a 302 Found redirect to the stored destination.

Authentication and API keys

When --auth is enabled, only authenticated POST requests can create short URLs, though GET requests for URL redirection remain unauthenticated. Use shortenerkey to manage users and API keys against the same SQLite database:

shortenerkey --database shortener.db create-user alice
shortenerkey --database shortener.db create-key alice

Then create a short URL with the returned key:

curl -X POST http://localhost:8080/ \
  -H 'Authorization: Bearer MY_API_KEY' \
  -d 'https://example.com/some/long/path'

Other management commands include:

list-users
delete-user <username>
check-key <key-or-hash>
list-keys <username>
delete-key <key-or-hash>

Run with Docker

Run the server and persist the database and logs in a local directory:

mkdir -p data
docker run --rm \
  -p 8080:8080 \
  -v "$PWD/data:/data" \
  zhongruoyu/shortener \
  --listen-port 8080 \
  --url-prefix http://localhost:8080/ \
  --sqlite-db /data/shortener.db \
  --log-file /data/access.log

You can also run shortenerkey inside the same image by overriding the entrypoint:

docker run --rm \
  --entrypoint shortenerkey \
  -v "$PWD/data:/data" \
  zhongruoyu/shortener \
  --database /data/shortener.db create-user alice

License

This project is licensed under the MIT License. See LICENSE.

shortener 0.1.1