mirror of
https://git.ikl.sh/132ikl/liteshort.git
synced 2023-08-10 21:13:04 +03:00
Split README into wiki pages
This commit is contained in:
132ikl
parent
8e9090bd89
commit
345d7b7dc6
122
README.md
122
README.md
@ -7,127 +7,11 @@ Click [here](https://ls.ikl.sh) for a live demo.
|
|||||||
|
|
||||||
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 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.
|
liteshort focuses on being configurable. There are over 15 config options and most updates will add more. Configuration is done through the easy-to-use YAML format.
|
||||||
The frontend is a basic POST form using [PureCSS](https://purecss.io).
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Installation
|
## 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.
|
Liteshort's installation process is dead-simple. Check out the [installation page](https://github.com/132ikl/liteshort/wiki/How-to-Install) for info on how to install.
|
||||||
|
|
||||||
```sh
|
|
||||||
git clone https://github.com/132ikl/liteshort
|
|
||||||
python3 -m venv venv
|
|
||||||
source venv/bin/activate
|
|
||||||
pip3 install -r requirements.txt 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 /usr/lib/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
|
|
||||||
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.
|
|
||||||
|
|
||||||
### Example Request
|
|
||||||
```
|
|
||||||
curl -u [admin_username]:[admin_password] \
|
|
||||||
-H "Accept: application/json" \
|
|
||||||
-d "api=delete" \
|
|
||||||
-d "short=[short]" \
|
|
||||||
[url]
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user