qshrtn

command module
v0.0.0-...-14d1989 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 27, 2020 License: GPL-3.0 Imports: 4 Imported by: 0

README

qshr.tn

CircleCI codecov

The server component for an anonymous, open-source URL shortening service.

README Index

API

Terminology

Term Description
Code A status code sent with all requests specifying the successfulness of a request
ID The path in which a redirect is from, qshr.tn/{id}
URL The URL in which a client will be redirected to if they send a GET request to qshr.tn/{id}

Get redirect

The function that handles these requests can be found in redirect.go and the tests in redirect_test.go.

Request

To get a redirect via the API you must send a GET request with the path /{id}/json.

Response

This endpoint will yield the following encoded as JSON:

Field Type Description Included
code int Status code Always
url string URL to redirect to When the code is success
error string Fatal error description When the code is internal server error

The status codes are as follows:

Code Description
0 Success
1 Not found
2 Internal server error

Example success response:

{
    "code": 0,
    "url":  "https://froogo.co.uk/"
}

Example not found response:

{
    "code": 1
}

Example internal server error response (EOF caused by bad JSON request body):

{
    "code":  2,
    "error": "EOF"
}

Create redirect

The function that handles these requests can be found in new.go and the tests in redirect_test.go.

Request

To create a new redirect you must send a POST request to /new/ with a JSON body.

The request body must be the following encoded as JSON:

Field Type Description Required
url string URL to redirect to Yes
id string Path to be redirected from No

If the ID is not included or empty, a random four character long ID will be generated.

Example request body with no id:

{
    "url": "https://froogo.co.uk/"
}

Example request body with an id:

{
    "url": "https://froogo.co.uk/",
    "id":  "frog"
}
Response

A request to this endpoint will yield the following encoded as JSON:

Field Type Description Included
code int Status code Always
id string Path to be redirected from When the code is success
error string Fatal error description When the code is internal server error

The status codes are as follows:

Code Description
0 Success
1 Internal server error
2 Forbidden domain (URL contains hostname (qshr.tn))
3 ID taken
4 Invalid URL

Example success response:

{
    "code": 0,
    "id":  "frog"
}

Example ID taken response:

{
    "code": 3
}

Example internal server error response (EOF caused by bad JSON request body):

{
    "code":  1,
    "error": "EOF"
}

How to host

This will assume you're using a Ubuntu 18.04 server; this isn't necessary.

As we will be using Docker to run this application, any Docker capable OS is fine.

Note: we'll be using the DB Docker Compose file for this as it fully encapsulates everything to make hosting easier. This isn't used on the official qshr.tn system as replica sets and load balancers are used to ensure redundancy.

Installing Docker (and Docker Compose)

I 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. Keep in mind, this is operating system specific and you may need a different guide for your case. Just Google "install docker YOUR OS", and find a trusted guide.

Install Docker on Ubuntu 18.04

Install Docker Compose on Ubuntu 18.04

Cloning the project

Assuming you have Git installed, go the directory in which you want to install qshr.tn, and execute this command:

git clone https://github.com/VolticFroogo/QShrtn

If you don't have Git installed, here's a guide for Ubuntu 18.04.

Setting up environment variables

Two environment files are used which you will need to create and configure: production.env and db.env.

These files must be in the root directory of the project.

production.env
Name Description
DB A MongoDB connection URI

Note: the root:password in this string must match the MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD in the db.env config.

Example file:

DB=mongodb://root:password@mongo/?authSource=admin&appname=qshrtn&ssl=false
db.env
Name Description
MONGO_INITDB_ROOT_USERNAME The root username
MONGO_INITDB_ROOT_PASSWORD The root password

Example file:

MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=password

Building and running

Change directory to the directory that you cloned earlier.

Then simply execute this command:

docker-compose -f docker-compose.db.yaml up --build

As the DB Docker Compose file states the application should restart unless stopped, this application will run after server restarts, updates, crashes, etc.

Customise site

To customise the site, simply edit any files in the static/ directory and rebuild:

docker-compose -f docker-compose.db.yaml up --build

Keep in mind, although everything by default uses a CDN for increased performance, all js, css, and img files are statically hosted.

So you can change them to local links like /css/main.min.css with no issues.

Updating

If you ever want to update the application, follow this:

Change directory to the directory that you cloned earlier.

Download the updates:

git pull

Rebuild and run:

docker-compose -f docker-compose.db.yaml up --build

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL