klein is a minimalist URL shortener written in Go. No unnecessary clutter, web UI, features, etc. Just shortening and serving redirections.
Modularity
klein has three core components that are abstracted into drivers to allow different functionality:
- auth
- Handles authentication, guarding access to shortening links
- Comes with two drivers:
- Unauthenticated—shorten URLs without authentication
- Static Key—require a static key/password
- HTTP Basic—uses HTTP Basic Auth, require a username and password
- alias
- Handles generating URL aliases.
- Comes with two drivers:
- Alphanumeric—returns a random alphanumeric string with a configurable length
- Memorable—returns a configurable amount of English words
- storage
- Handles storing and reading shortened URLs.
- Comes with four drivers:
- File—stores data as text files in a directory
- Bolt—stores data in a bolt database
- Redis—stores data in a redis database (ensure you configure save)
- Spaces.stateful—stores data as a single file in DigitalOcean Spaces
- Spaces.stateless—stores each URL as an object in DigitalOcean Spaces
- PostgreSQL—stores data in a PostgreSQL database
- Memory—stores data in a temporary map in memory
Usage
Once installed and configured, there are two actions that you can do:
- Shorten a URL:
- Send a POST request to
/with the following two fields:url—the URL to shortenkey—if the Static Key auth driver is enabledalias—a custom alias to be used instead of a randomly-generated one
- Example cURL command:
curl -X POST -d 'url=http://github.com/kamaln7/klein' -d 'key=secret_password' -d 'alias=klein_gh' http://localhost:5556/- This will create a short URL at
http://localhost:5556/klein_ghthat redirects tohttp://github.com/kamaln7/klein.
- This will create a short URL at
- Send a POST request to
- Look up a URL/serve a redirect:
- Browse to
http://[path to klein]/[alias]to access a short URL.
- Browse to
Installation
kamaln7/klein. The latest tag is a good bet. See the releases page for version numbers.
Or grab the latest binary from the releases page and drop it in /usr/local/bin, /opt, or wherever you like.
Configuration
klein uses CLI options or environment variables for config. For environment variables, each option is prefixed with klein and both dots and dashes are replaced with underscores, eg the environment variable for the storage.spaces.access-key option is KLEIN_STORAGE_SPACES_ACCESS_KEY.
Running klein without any configuration will use the following default config:
- Aliases are random 5-character alphanumeric strings
- Listens on 127.0.0.1:5556
- No authentication
- Stores URLs as files in a
urlsdirectory in the current working directory
Full list of config options
$ klein --help
klein is a minimalist URL shortener.
Usage:
klein [flags]
Flags:
--alias.alphanumeric.alpha use letters in code (default true)
--alias.alphanumeric.length int alphanumeric code length (default 5)
--alias.alphanumeric.num use numbers in code (default true)
--alias.driver string what alias generation to use (alphanumeric, memorable) (default "alphanumeric")
--alias.memorable.length int memorable word count (default 3)
--auth.basic.password string password for HTTP basic auth
--auth.basic.username string username for HTTP basic auth
--auth.driver string what auth backend to use (basic, key, none) (default "none")
--auth.key string upload API key
--error-template string path to error template
-h, --help help for klein
--listen string listen address (default "127.0.0.1:5556")
--root string root redirect
--storage.boltdb.path string path to use for bolt db (default "bolt.db")
--storage.driver string what storage backend to use (file, boltdb, redis, spaces.stateful, sql.pg, memory) (default "file")
--storage.file.path string path to use for file store (default "urls")
--storage.redis.address string address:port of redis instance (default "127.0.0.1:6379")
--storage.redis.auth string password to access redis
--storage.redis.db int db to select within redis
--storage.spaces.access-key string access key for spaces
--storage.spaces.region string region for spaces
--storage.spaces.secret-key string secret key for spaces
--storage.spaces.space string space to use
--storage.spaces.stateful.path string path of the file in spaces (default "klein.json")
--storage.spaces.stateless.cache-duration duration time to cache spaces results in memory. 0 to disable (default 1m0s)
--storage.spaces.stateless.path string path of the directory in spaces to store urls in (default "/klein")
--storage.sql.pg.database string postgresql database (default "klein")
--storage.sql.pg.host string postgresql host (default "localhost")
--storage.sql.pg.password string postgresql password (default "secret")
--storage.sql.pg.port int32 postgresql port (default 5432)
--storage.sql.pg.sslmode string postgresql sslmode (default "prefer")
--storage.sql.pg.table string postgresql table (default "klein")
--storage.sql.pg.user string postgresql user (default "klein")
--url string path to public facing url
Service file
Here's a Systemd service file that you can use with klein:
[Unit]
Description=klein
After=network-online.target
[Service]
Restart=on-failure
User=klein
Group=klein
ExecStart=/usr/local/bin/klein
[Install]
WantedBy=multi-user.target
Don't forget to add your config to the ExecStart line and update User and Group if necessary. Make sure that klein has permission to write to the URLs directory.
Development
To manage dependencies, we use Go modules.
To build the app, run go build.
This will produce a binary named klein. You can now run the app by running ./klein
❤️ Contributors
- @LukeHandle
- @DMarby
License
See ./LICENSE