README.md 5.84 KB
Newer Older
132ikl's avatar
132ikl committed
1 2 3
# liteshort
liteshort is a link shortener designed with lightweightness, user and sysadmin-friendliness, privacy, and configurability in mind.

4 5
Click [here](https://ls.ikl.sh) for a live demo.

132ikl's avatar
132ikl committed
6
*Why liteshort over other URL shorteners?*
132ikl's avatar
132ikl committed
7

132ikl's avatar
132ikl committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
liteshort is designed with the main goal of being lightweight. It does away with all the frills of other link shorteners and allows the best of the basics at a small resource price. liteshort uses under 20 MB of memory idle, per worker. liteshort has an easy-to-use API and web interface. liteshort doesn't store any more information than necessary: just the long and short URLs. It does not log the date of creation, the remote IP, or any other information.

liteshort uses Python 3, [Flask](http://flask.pocoo.org/), SQLite3, and [uwsgi](https://uwsgi-docs.readthedocs.io/en/latest/) for the backend. 
The frontend is a basic POST form using [PureCSS](https://purecss.io).

![liteshort screenshot](https://fs.ikl.sh/selif/4cgndb6e.png)

## Installation
This installation procedure assumes that you plan to installing using a web server reverse proxy through a unix socket. This guide is loosely based upon DigitalOcean's [Flask/uWSGI/nginx guide](https://www.digitalocean.com/community/tutorials/how-to-serve-flask-applications-with-uswgi-and-nginx-on-ubuntu-18-04).
Before installing, you must the following or your distribution's equivalent must be installed:
* python3-pip 
* python3-dev 
* python3-setuptools
* python3-venv
* build-essential

Start in the directory you wish to install to and modify to fit your installation. It is recommended to use a user specifically for liteshort and the www-data group for your installation folder.

```sh
git clone https://github.com/132ikl/liteshort
python3 -m venv virtualenv
source virtualenv/bin/activate
pip install wheel
pip install bcrypt flask pyyaml uwsgi
```

Edit `liteshort.ini` and `liteshort.service` as seen fit. Then edit `config.yml` according to the [Configuration](#configuration) section.

Finally,
```sh
cp liteshort.service /etc/systemd/system/
systemctl enable liteshort
systemctl start liteshort
```

liteshort is now accessible through a reverse proxy. The socket file is created in the install path.

## Configuration
The configuration file has an explanation for each option. This section will detail the mandatory options to be set before the program is able to be started.

`admin_hashed_password` or `admin_password`
* These must be set in order to use the API. If you do not care about the API, simply set `disable_api` to true.
As to not store the API password in cleartext, `admin_hashed_password` is preferred over `admin_password`. Run `securepass.sh` in order to generate the password hash. Set `admin_hashed_password` to the output of the script, excluding the username header at the beginning of the hash.
Note that using admin_hashed_password is more resource-intensive than `admin_password`, so the API will be noticeably slower when using `admin_hashed_password`.

`secret_key`
* This is used for cookies in order to store messages between requests. It should be a randomized key 12-16 characters, comprised of letters, number, and symbols. A standard password from a generator works fine.


## API
All API requests should have the POST form data `format` set to `json`.
In order to create a new short URL, simply make a POST request with the form data `long` set to your long link and, optionally, set `short` to your short link.
Everything other than creation of links requires BasicAuth using the username and password defined in the configuration file. To use the following commands, set `api` to the command in the form data of your request.
* `list` and `listshort`
    * Lists all links the the database, sorted by short links.
* `listlong`
    * Lists all links in the database, sorted by long links.
* `delete`
    * Deletes a URL. In the form data, set `short` to the short link you want to delete, or set `long` to delete all short links that redirect to the provided long link.
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
    
## Using a reverse proxy
The following are barebones examples of an nginx proxy for liteshort, meaning it doesn't have SSL or anything fancy. You may also use a non-nginx webserver by making a config equivalent for it based upon the following configurations. Make sure your webserver is serving the /static/ folder. While liteshort can serve the folder, webservers are much more efficient at serving static files.

### On domain root


```
server {

    listen 80;

    server_name example.com;
    
    location ^~ /static/  {
         include  /etc/nginx/mime.types;
         root /usr/local/liteshort/;
    }

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/path/to/liteshort/liteshort.sock;
    }
}
```

### On a subdomain
First, make sure `site_domain` and `subdomain` options are set in config.yml. If you want the web interface on a subdomain, but the actual shortlinks on the main domain, as seen on the [demo site](https://ls.ikl.sh), use a configuration akin to the following. Make sure that anything you want to happen before liteshort, like a homepage on /, has its location block BEFORE the rewrite block. Nginx goes in numerical order of location blocks, so the rewrite location block will redirect everything on / to liteshort if not the last block.

```
server {

    listen 80;

    server_name subdomain.example.com;

    location / {
        include uwsgi_params;
        uwsgi_pass unix:/path/to/liteshort/liteshort.sock;
    }
}

server {

    listen 80;
 
    server_name example.com;
    
    location ^~ /static/  {
         include  /etc/nginx/mime.types;
         root /usr/local/liteshort/;
    }
    
    location / {
        rewrite /example/subdomain.example(.+) /$1 break;
        include uwsgi_params;
        uwsgi_pass unix:/usr/local/liteshort/liteshort.sock;
    }
}
```