lukehandle / klein Goto Github PK

klein is a minimalist URL shortener written in Go. No unnecessary clutter, web UI, features, etc. Just shortening and serving redirections.

klein has three core components that are abstracted into "modules" to allow different functionality:

1. auth
   • Handles authentication, gaurding access to shortening links
   • Comes with two modules:
     • Unauthenticated—shorten URLs without authentication
     • Static Key—require a static key/password
2. alias
   • Handles generating URL aliases.
   • Comes with two modules:
     • Alphanumeric—returns a random alphanumeric string with a configurable length
     • Memorable-returns a configurable amount of English words
3. storage
   • Handles storing and reading shortened URLs.
   • Comes with two modules:
     • File—stores URL data as text files in a directory
     • Bolt—stores URL data in a bolt database

Grab the latest binary from the releases page and drop it in /usr/local/bin, /opt, or wherever you like.

klein uses CLI options for config.

You must specify one storage provider (file.path/bolt.path) and one alias provider (alphanumeric.length/memorable.length).

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.

Once installed and configured, there are two actions that you can do:

1. Shorten a URL:
   • Send a POST request to / with the following two fields:
     1. url—the URL to shorten
     2. key—if the Static Key auth module is enabled
     3. alias—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_gh that redirects to http://github.com/kamaln7/klein.
2. Look up a URL/serve a redirect:
   • Browse to http://[path to klein]/[alias] to access a short URL.

Copyright 2017 Kamal Nasser

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.