{"id":17786973,"url":"https://github.com/kamaln7/klein","last_synced_at":"2025-03-16T07:31:47.532Z","repository":{"id":48060174,"uuid":"98466865","full_name":"kamaln7/klein","owner":"kamaln7","description":"the minimalist URL shortener","archived":false,"fork":false,"pushed_at":"2023-02-24T19:21:41.000Z","size":121,"stargazers_count":50,"open_issues_count":9,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-27T05:25:32.909Z","etag":null,"topics":["go","golang","minimalist","url-shortener"],"latest_commit_sha":null,"homepage":"https://kmln.sr/klein","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kamaln7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-26T21:21:45.000Z","updated_at":"2025-02-11T21:33:28.000Z","dependencies_parsed_at":"2024-06-19T00:17:40.153Z","dependency_job_id":"8a7926cf-aec3-4f2c-8621-d80ff0aa322f","html_url":"https://github.com/kamaln7/klein","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamaln7%2Fklein","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamaln7%2Fklein/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamaln7%2Fklein/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamaln7%2Fklein/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kamaln7","download_url":"https://codeload.github.com/kamaln7/klein/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243806035,"owners_count":20350775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","minimalist","url-shortener"],"created_at":"2024-10-27T10:09:02.897Z","updated_at":"2025-03-16T07:31:46.961Z","avatar_url":"https://github.com/kamaln7.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"/klein.png\" alt=\"klein logo\" width=\"386\" /\u003e\n\u003c/p\u003e\n\nklein is a minimalist URL shortener written in Go. No unnecessary clutter, web UI, features, etc. Just shortening and serving redirections.\n\n## Modularity\n\nklein has three core components that are abstracted into drivers to allow different functionality:\n\n1. auth\n   - Handles authentication, guarding access to shortening links\n   - Comes with two drivers:\n     - Unauthenticated—shorten URLs without authentication\n     - Static Key—require a static key/password\n     - HTTP Basic—uses HTTP Basic Auth, require a username and password\n2. alias\n   - Handles generating URL aliases.\n   - Comes with two drivers:\n     - Alphanumeric—returns a random alphanumeric string with a configurable length\n     - Memorable—returns a configurable amount of English words\n3. storage\n   - Handles storing and reading shortened URLs.\n   - Comes with four drivers:\n     - File—stores data as text files in a directory\n     - Bolt—stores data in a [bolt](https://github.com/boltdb/bolt) database\n     - Redis—stores data in a [redis](https://redis.io/) database (ensure you configure save)\n     - Spaces.stateful—stores data as a single file in [DigitalOcean Spaces](https://do.co/spaces)\n     - Spaces.stateless—stores each URL as an object in [DigitalOcean Spaces](https://do.co/spaces)\n     - PostgreSQL—stores data in a [PostgreSQL](https://www.postgresql.org) database\n     - Memory—stores data in a temporary map in memory\n\n## Usage\n\nOnce installed and configured, there are two actions that you can do:\n\n1. Shorten a URL:\n   - Send a POST request to `/` with the following two fields:\n     1. `url`—the URL to shorten\n     2. `key`—if the Static Key auth driver is enabled\n     3. `alias`—a custom alias to be used instead of a randomly-generated one\n   - Example cURL command: `curl -X POST -d 'url=http://github.com/kamaln7/klein' -d 'key=secret_password' -d 'alias=klein_gh' http://localhost:5556/`\n     - This will create a short URL at `http://localhost:5556/klein_gh` that redirects to `http://github.com/kamaln7/klein`.\n2. Look up a URL/serve a redirect:\n   - Browse to `http://[path to klein]/[alias]` to access a short URL.\n\n## Installation\n\n✅ Use the docker image `kamaln7/klein`. The `latest` tag is a good bet. See [the releases page](https://github.com/kamaln7/klein/releases) for version numbers.\n\nOr grab the latest binary from [the releases page](https://github.com/kamaln7/klein/releases) and drop it in `/usr/local/bin`, `/opt`, or wherever you like.\n\n### Configuration\n\nklein 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`.\n\nRunning klein without any configuration will use the following default config:\n\n- Aliases are random 5-character alphanumeric strings\n- Listens on 127.0.0.1:5556\n- No authentication\n- Stores URLs as files in a `urls` directory in the current working directory\n\n#### Full list of config options\n\n```\n$ klein --help\nklein is a minimalist URL shortener.\n\nUsage:\n  klein [flags]\n\nFlags:\n      --alias.alphanumeric.alpha                           use letters in code (default true)\n      --alias.alphanumeric.length int                      alphanumeric code length (default 5)\n      --alias.alphanumeric.num                             use numbers in code (default true)\n      --alias.driver string                                what alias generation to use (alphanumeric, memorable) (default \"alphanumeric\")\n      --alias.memorable.length int                         memorable word count (default 3)\n      --auth.basic.password string                         password for HTTP basic auth\n      --auth.basic.username string                         username for HTTP basic auth\n      --auth.driver string                                 what auth backend to use (basic, key, none) (default \"none\")\n      --auth.key string                                    upload API key\n      --error-template string                              path to error template\n  -h, --help                                               help for klein\n      --listen string                                      listen address (default \"127.0.0.1:5556\")\n      --root string                                        root redirect\n      --storage.boltdb.path string                         path to use for bolt db (default \"bolt.db\")\n      --storage.driver string                              what storage backend to use (file, boltdb, redis, spaces.stateful, sql.pg, memory) (default \"file\")\n      --storage.file.path string                           path to use for file store (default \"urls\")\n      --storage.redis.address string                       address:port of redis instance (default \"127.0.0.1:6379\")\n      --storage.redis.auth string                          password to access redis\n      --storage.redis.db int                               db to select within redis\n      --storage.spaces.access-key string                   access key for spaces\n      --storage.spaces.region string                       region for spaces\n      --storage.spaces.secret-key string                   secret key for spaces\n      --storage.spaces.space string                        space to use\n      --storage.spaces.stateful.path string                path of the file in spaces (default \"klein.json\")\n      --storage.spaces.stateless.cache-duration duration   time to cache spaces results in memory. 0 to disable (default 1m0s)\n      --storage.spaces.stateless.path string               path of the directory in spaces to store urls in (default \"/klein\")\n      --storage.sql.pg.database string                     postgresql database (default \"klein\")\n      --storage.sql.pg.host string                         postgresql host (default \"localhost\")\n      --storage.sql.pg.password string                     postgresql password (default \"secret\")\n      --storage.sql.pg.port int32                          postgresql port (default 5432)\n      --storage.sql.pg.sslmode string                      postgresql sslmode (default \"prefer\")\n      --storage.sql.pg.table string                        postgresql table (default \"klein\")\n      --storage.sql.pg.user string                         postgresql user (default \"klein\")\n      --url string                                         path to public facing url\n```\n\n### Service file\n\nHere's a Systemd service file that you can use with klein:\n\n```\n[Unit]\nDescription=klein\nAfter=network-online.target\n\n[Service]\nRestart=on-failure\n\nUser=klein\nGroup=klein\n\nExecStart=/usr/local/bin/klein\n\n[Install]\nWantedBy=multi-user.target\n```\n\nDon'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.\n\n## Development\n\nTo manage dependencies, we use [Go modules](https://blog.golang.org/using-go-modules).\n\nTo build the app, run `go build`.  \nThis will produce a binary named `klein`. You can now run the app by running `./klein`\n\n### ❤️ Contributors\n\n- @LukeHandle\n- @DMarby\n\n## License\n\nSee [./LICENSE](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamaln7%2Fklein","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkamaln7%2Fklein","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamaln7%2Fklein/lists"}