shortlinks

A fast, SQLite-backed URL shortener compatible with the YOURLS API. It includes short-link redirects, click tracking, an HTMX admin interface, authentication, CSV import, and optional GeoIP lookup.

Run

Requires Go, CGO, and a C compiler.

make dev

The service starts at http://localhost:8080. Create a link with:

curl -X POST http://localhost:8080/api \
  -d action=shorturl \
  -d format=json \
  --data-urlencode url=https://example.com

Use DEV_ARGS to override defaults:

make dev DEV_ARGS='--addr :8081 --public-url http://localhost:8081 --sqlite-path data/dev.db'

Configuration

Configuration is loaded in this order: defaults, YAML file, SHORTLINKS_ environment variables, then CLI flags. See config.example.yaml for all options.

The API is available at /api and the YOURLS-compatible /yourls-api.php. Supported actions are shorturl, stats, db-stats, url-stats, expand, and version; output formats are JSON, JSONP, XML, and plain text.

Migrations run automatically at startup and can also be managed manually:

go run ./cmd/shortlinks migrate up --sqlite-path data/shortlinks.db
go run ./cmd/shortlinks migrate down --sqlite-path data/shortlinks.db

Development

make generate   # regenerate API and database code
make spec-lint  # lint the OpenAPI specification
make test
make bench

Database definitions are in specs/db; the API specification is in specs/openapi/openapi.yaml.