{"id":37154828,"url":"https://github.com/volticfroogo/qshrtn","last_synced_at":"2026-01-14T18:18:43.157Z","repository":{"id":57515933,"uuid":"200719020","full_name":"VolticFroogo/QShrtn","owner":"VolticFroogo","description":"The server component for an anonymous, open-source URL shortening service.","archived":false,"fork":false,"pushed_at":"2021-01-24T10:17:00.000Z","size":131,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-06-21T15:37:49.028Z","etag":null,"topics":["go","server","url-shortener"],"latest_commit_sha":null,"homepage":"https://qshr.tn","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VolticFroogo.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}},"created_at":"2019-08-05T19:48:41.000Z","updated_at":"2021-01-24T10:17:02.000Z","dependencies_parsed_at":"2022-08-28T16:51:12.265Z","dependency_job_id":null,"html_url":"https://github.com/VolticFroogo/QShrtn","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VolticFroogo/QShrtn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolticFroogo%2FQShrtn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolticFroogo%2FQShrtn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolticFroogo%2FQShrtn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolticFroogo%2FQShrtn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VolticFroogo","download_url":"https://codeload.github.com/VolticFroogo/QShrtn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VolticFroogo%2FQShrtn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28430315,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","server","url-shortener"],"created_at":"2026-01-14T18:18:42.691Z","updated_at":"2026-01-14T18:18:43.145Z","avatar_url":"https://github.com/VolticFroogo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qshr.tn\n[![CircleCI](https://circleci.com/gh/VolticFroogo/QShrtn.svg?style=svg)](https://circleci.com/gh/VolticFroogo/QShrtn)\n[![codecov](https://codecov.io/gh/VolticFroogo/QShrtn/branch/master/graph/badge.svg)](https://codecov.io/gh/VolticFroogo/QShrtn)\n\n The server component for an anonymous, open-source URL shortening service.\n\n## README Index\n- [API](#api)\n\t- [Terminology](#terminology)\n\t- [Get redirect](#get-redirect)\n\t\t- [Request](#request)\n\t\t- [Response](#response)\n\t- [Create redirect](#create-redirect)\n\t    - [Request](#request-1)\n    \t- [Response](#response-1)\n- [How to host](#how-to-host)\n    - [Installing Docker (and Docker Compose)](#installing-docker-and-docker-compose)\n    - [Cloning the project](#cloning-the-project)\n    - [Setting up environment variables](#setting-up-environment-variables)\n        - [production.env](#productionenv)\n        - [db.env](#dbenv)\n    - [Updating](#updating)\n- [Setup ShareX](sharex.md)\n\n# API\n## Terminology\nTerm | Description\n---- | -----------\nCode | A status code sent with all requests specifying the successfulness of a request\nID   | The path in which a redirect is from, `qshr.tn/{id}`\nURL  | The URL in which a client will be redirected to if they send a `GET` request to `qshr.tn/{id}`\n\n## Get redirect\nThe function that handles these requests can be found in [redirect.go](redirect/redirect.go) and the tests in [redirect_test.go](redirect/redirect_test.go).\n\n### Request\nTo get a redirect via the API you must send a `GET` request with the path `/{id}/json`.\n\n### Response\nThis endpoint will yield the following encoded as JSON:\n\nField | Type   | Description             | Included\n----- | ------ | ----------------------- | ---------\ncode  | int    | Status code             | Always\nurl   | string | URL to redirect to      | When the code is success\nerror | string | Fatal error description | When the code is internal server error\n\nThe status codes are as follows:\n\nCode | Description\n---- | -----------\n0    | Success\n1    | Not found\n2    | Internal server error\n\nExample success response:\n```json\n{\n    \"code\": 0,\n    \"url\":  \"https://froogo.co.uk/\"\n}\n```\n\nExample not found response:\n```json\n{\n    \"code\": 1\n}\n```\n\nExample internal server error response (EOF caused by bad JSON request body):\n```json\n{\n    \"code\":  2,\n    \"error\": \"EOF\"\n}\n```\n\n## Create redirect\nThe function that handles these requests can be found in [new.go](redirect/new.go) and the tests in [redirect_test.go](redirect/redirect_test.go).\n\n### Request\nTo create a new redirect you must send a `POST` request to `/new/` with a JSON body.\n\nThe request body must be the following encoded as JSON:\n\nField | Type   | Description                | Required\n----- | ------ | -------------------------- | ---------\nurl   | string | URL to redirect to         | Yes\nid    | string | Path to be redirected from | No\n\nIf the ID is not included or empty, a random four character long ID will be generated.\n\nExample request body with no id:\n```json\n{\n    \"url\": \"https://froogo.co.uk/\"\n}\n```\n\nExample request body with an id:\n```json\n{\n    \"url\": \"https://froogo.co.uk/\",\n    \"id\":  \"frog\"\n}\n```\n\n### Response\nA request to this endpoint will yield the following encoded as JSON:\n\nField | Type   | Description                | Included\n----- | ------ | -------------------------- | ---------\ncode  | int    | Status code                | Always\nid    | string | Path to be redirected from | When the code is success\nerror | string | Fatal error description    | When the code is internal server error\n\nThe status codes are as follows:\n\nCode | Description\n---- | -----------\n0    | Success\n1    | Internal server error\n2    | Forbidden domain (URL contains hostname (qshr.tn))\n3    | ID taken\n4    | Invalid URL\n\nExample success response:\n```json\n{\n    \"code\": 0,\n    \"id\":  \"frog\"\n}\n```\n\nExample ID taken response:\n```json\n{\n    \"code\": 3\n}\n```\n\nExample internal server error response (EOF caused by bad JSON request body):\n```json\n{\n    \"code\":  1,\n    \"error\": \"EOF\"\n}\n```\n\n# How to host\nThis will assume you're using a Ubuntu 18.04 server; this isn't necessary.\n\nAs we will be using Docker to run this application, any Docker capable OS is fine.\n\nNote: we'll be using the [DB Docker Compose file](docker-compose.db.yaml) for this as it fully encapsulates everything to make hosting easier.\nThis isn't used on the official qshr.tn system as replica sets and load balancers are used to ensure redundancy.\n\n## Installing Docker (and Docker Compose)\nI won't go over this as there are hundreds of guides on this online, but I will link what I recommend for Ubuntu 18.04.\nKeep in mind, this is operating system specific and you may need a different guide for your case.\nJust Google \"install docker YOUR OS\", and find a trusted guide.\n\n[Install Docker on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04)\n\n[Install Docker Compose on Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04)\n\n## Cloning the project\nAssuming you have Git installed, go the directory in which you want to install qshr.tn, and execute this command:\n\n`git clone https://github.com/VolticFroogo/QShrtn`\n\nIf you don't have Git installed, [here's a guide for Ubuntu 18.04](https://www.digitalocean.com/community/tutorials/how-to-install-git-on-ubuntu-18-04).\n\n## Setting up environment variables\nTwo environment files are used which you will need to create and configure: `production.env` and `db.env`.\n\nThese files must be in the root directory of the project.\n\n### production.env\nName   | Description\n------ | -----------\nDB     | [A MongoDB connection URI](https://docs.mongodb.com/manual/reference/connection-string/)\n\nNote: the `root:password` in this string must match the `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD` in the [db.env](#dbenv) config.\n\nExample file:\n```\nDB=mongodb://root:password@mongo/?authSource=admin\u0026appname=qshrtn\u0026ssl=false\n```\n\n### db.env\nName                       | Description\n-------------------------- | -----------\nMONGO_INITDB_ROOT_USERNAME | The root username\nMONGO_INITDB_ROOT_PASSWORD | The root password\n\nExample file:\n```\nMONGO_INITDB_ROOT_USERNAME=root\nMONGO_INITDB_ROOT_PASSWORD=password\n```\n\n## Building and running\nChange directory to the [directory that you cloned](#cloning-the-project) earlier.\n\nThen simply execute this command:\n\n`docker-compose -f docker-compose.db.yaml up --build`\n\nAs the [DB Docker Compose file](docker-compose.db.yaml) states the application should restart unless stopped,\nthis application will run after server restarts, updates, crashes, etc.\n\n## Customise site\nTo customise the site, simply edit any files in the `static/` directory and rebuild:\n\n`docker-compose -f docker-compose.db.yaml up --build`\n\nKeep in mind, although everything by default uses a CDN for increased performance, all js, css, and img files are statically hosted.\n\nSo you can change them to local links like `/css/main.min.css` with no issues.\n\n## Updating\nIf you ever want to update the application, follow this:\n\nChange directory to the [directory that you cloned](#cloning-the-project) earlier.\n\nDownload the updates:\n\n`git pull`\n\nRebuild and run:\n\n`docker-compose -f docker-compose.db.yaml up --build`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolticfroogo%2Fqshrtn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolticfroogo%2Fqshrtn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolticfroogo%2Fqshrtn/lists"}