README.md 3.41 KB
Newer Older
Luc Didry's avatar
Luc Didry committed
1 2
# Lstu

Luc Didry's avatar
Luc Didry committed
3
## What does Lstu mean?
Luc Didry's avatar
Luc Didry committed
4 5 6

It means Let's Shorten That Url.

Luc Didry's avatar
Luc Didry committed
7
## License
Luc Didry's avatar
Luc Didry committed
8

9
Lstu is licensed under the terms of the WTFPL. See the LICENSE file.
Luc Didry's avatar
Luc Didry committed
10

Luc Didry's avatar
Luc Didry committed
11
## Dependencies
Luc Didry's avatar
Luc Didry committed
12

13
* Carton : Perl dependencies manager, it will get what you need, so don't bother about dependencies (but you can read the file `cpanfile` if you want).
Luc Didry's avatar
Luc Didry committed
14

15
```shell
Luc Didry's avatar
Luc Didry committed
16
sudo cpan Carton
Luc Didry's avatar
Luc Didry committed
17 18
```

Luc Didry's avatar
Luc Didry committed
19
## Installation
20

Luc Didry's avatar
Luc Didry committed
21
After installing Carton :
Luc Didry's avatar
Luc Didry committed
22

23
```shell
24
git clone https://framagit.org/luc/lstu.git
Luc Didry's avatar
Luc Didry committed
25 26
cd lstu
carton install
Luc Didry's avatar
Luc Didry committed
27
cp lstu.conf.template lstu.conf
28
vi lstu.conf
Luc Didry's avatar
Luc Didry committed
29 30
```

31 32
The configuration file is self-documented.

Luc Didry's avatar
Luc Didry committed
33
## Usage
Luc Didry's avatar
Luc Didry committed
34

35 36 37 38
### Launch manually

This is good for test, not for production.

Luc Didry's avatar
Luc Didry committed
39
```
40
# start it
41
carton exec hypnotoad script/lstu
42 43
# stop it
carton exec hypnotoad -s script/lstu
Luc Didry's avatar
Luc Didry committed
44 45
```

46
Yup, that's all, it will listen at "http://127.0.0.1:8080".
Luc Didry's avatar
Luc Didry committed
47

48
For more options (interfaces, user, etc.), change the configuration in `lstu.conf` (have a look at http://mojolicio.us/perldoc/Mojo/Server/Hypnotoad#SETTINGS for the available options).
Luc Didry's avatar
Luc Didry committed
49

50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
### Systemd

```
sudo su
cp utilities/lstu.service /etc/systemd/system/
vi /etc/systemd/system/lstu.service
systemctl daemon-reload
systemctl enable lstu.service
systemctl start lstu.service
```

### SysVinit

```
sudo su
cp utilities/lstu.default /etc/default/lstu
vi /etc/default/lstu
cp utilities/lstu.init /etc/init.d/lstu
update-rc.d lstu defaults
service lstu start
```

Luc Didry's avatar
Luc Didry committed
72 73 74 75
## Other options

There is the `contact` option (mandatory), where you have to put some way for the users to contact you, and the `secret` where you have to put a random string in order to protect your Mojolicious cookies (not really useful and optional).

76
Please, have a look at the `lstu.conf.template`, it's full of options and is self-documented.
Luc Didry's avatar
Luc Didry committed
77

78
## How many URLs can it handle ?
79

Luc Didry's avatar
Luc Didry committed
80
By default, there are 8 361 453 672 available combinations. I think the sqlite db will explode before you reach this limit. If you want more shortened URLs than that, open `lstu.conf` and change the `length` setting.
81

82
Every time somebody uses Lstu, it will create 'waiting' shortened URLs codes in order to be quick to shorten the URLs.
83

Luc Didry's avatar
Luc Didry committed
84 85 86
Accordingly to the `lstu.conf` configuration file, it will create `provisioning` waiting URLs, adding them `provis_step` by `provis_step`.

This provisioning asks to modify your database if you're updating Lstu from 0.01 to 0.02:
87 88
```shell
sqlite3 lstu.db
Luc Didry's avatar
Luc Didry committed
89
```
90 91 92 93 94

```SQL
PRAGMA writable_schema = 1;
UPDATE SQLITE_MASTER SET SQL = 'CREATE TABLE lstu (short TEXT PRIMARY KEY, url TEXT, counter INTEGER, timestamp INTEGER)' WHERE NAME = 'lstu';
PRAGMA writable_schema = 0;
Luc Didry's avatar
Luc Didry committed
95
```
96

Luc Didry's avatar
Luc Didry committed
97
## Reverse proxy
Luc Didry's avatar
Luc Didry committed
98

Luc Didry's avatar
Luc Didry committed
99
For Nginx, use `utilities/lstu.nginx` as a template for your virtualhost configuration.
Luc Didry's avatar
Luc Didry committed
100

Luc Didry's avatar
Luc Didry committed
101
## Internationalization
102

Luc Didry's avatar
Luc Didry committed
103 104 105
Lstu comes with English and French languages. It will choose the language to display with the browser's settings.

If you want to add more languages, please help on <https://www.transifex.com/projects/p/lstu/>
106

Luc Didry's avatar
Luc Didry committed
107 108 109
There are just a few sentences, so it will be quick to translate.

If you add sentences to translate, just do `make locales` to update the en.po file and don't forget to update the others translation files.
110

Luc Didry's avatar
Luc Didry committed
111
## Official instance
Luc Didry's avatar
Luc Didry committed
112 113

You can see it working and use it at https://lstu.fr.
Luc Didry's avatar
Luc Didry committed
114

Luc Didry's avatar
Luc Didry committed
115
## API
Luc Didry's avatar
Luc Didry committed
116

Luc Didry's avatar
Luc Didry committed
117
See https://lstu.fr/api
Luc Didry's avatar
Luc Didry committed
118

Luc Didry's avatar
Luc Didry committed
119 120 121 122
## Contributing

See the [contributing guidelines](CONTRIBUTING.md).

Luc Didry's avatar
Luc Didry committed
123
## Other projects dependencies
Luc Didry's avatar
Luc Didry committed
124

125
Lstu is written in Perl with the Mojolicious framework and uses the Twitter bootstrap framework to look not too ugly.
Luc Didry's avatar
Luc Didry committed
126 127 128 129

## Authors

See the [AUTHORS.md](AUTHORS.md) file.