Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@amitt001
amitt001 committed Jul 10, 2022
1 parent f28ed9e commit 88c7c31
Showing 1 changed file with 46 additions and 97 deletions.
143 changes: 46 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,29 @@
<p align="center"><img src="pygmyui/static/logo/logov2.png" alt="pygmy" height="200px"></p>

# Pygmy
<div align="center">
<h1>Pygmy</h1>

<!-- [![Build Status](https://travis-ci.org/amitt001/pygmy.svg?branch=master)](https://travis-ci.org/amitt001/pygmy) -->

[![Build Status](https://travis-ci.org/amitt001/pygmy.svg?branch=master)](https://travis-ci.org/amitt001/pygmy)
[![Coverage Status](https://img.shields.io/coveralls/github/amitt001/pygmy.svg?color=yellowgreen)](https://coveralls.io/github/amitt001/pygmy?branch=master)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/Django.svg)
[![PyPI license](https://img.shields.io/pypi/l/ansicolortags.svg)](https://github.com/amitt001/pygmy/blob/master/LICENSE)
![Docker Pulls](https://img.shields.io/docker/pulls/amit19/pygmy.svg)
[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.me/amit19)

Live version of this project @ [https://pygy.co](https://pygy.co)
Demo Version: [https://pygy.co](https://pygy.co)

Check link stats by adding **+** to the URL. Example [pygy.co/pygmy+](https://pygy.co/pygmy+)
Link stats(add **+** to the URL) example: [pygy.co/pygmy+](https://pygy.co/pygmy+)

Hackernews Thread: [https://news.ycombinator.com/item?id=17690559](https://pygy.co/pygmyHN)

*Note that pygy.co is a demo website for this project and should be used as such. While the website is going to be up for the foreseeable future, its future depends on the sponsorship and hosting that I get. Currently, the project is hosted on Digitalocean, as they were kind enough to offer me one year of sponsorship. I would like to keep the project website up and maintain the project but I do not make any financial gains out of this project or website. Website is
free to use and is completely ad-free.
If you would like to support the project, Please use the donate link in [Donations](#donations) section.*
</div>

# Table of Contents
- [Pygmy](#pygmy)
- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Technical Info](#technical-info)
- [Installation/Setup](#installationsetup)
- [Docker](#docker)
- [Manual(from source)](#manualfrom-source)
- [Features](#features)
- [Technical Info](#technical-info)
- [Setup](#setup)
- [Docker](#docker)
- [Manual(from source)](#manualfrom-source)
- [DB Setup:](#db-setup)
- [Use MySQL](#use-mysql)
- [Use Postgresql](#use-postgresql)
Expand All @@ -35,13 +32,10 @@ If you would like to support the project, Please use the donate link in [Donatio
- [Using Pygmy API](#using-pygmy-api)
- [Create User:](#create-user)
- [Shell Usage](#shell-usage)
- [How Link Stats Are Generated?](#how-link-stats-are-generated)
- [How Pygmy Auth Token Works?](#how-pygmy-auth-token-works)
- [Development](#development)
- [Contributions](#contributions)
- [Donations](#donations)
- [Sponsorship](#sponsorship)
- [License](#license)
- [Development](#development)
- [Run tests:](#run-tests)
- [Run tests with coverage report](#run-tests-with-coverage-report)
- [License](#license)

Pygmy or `pygy.co` is an open-source, extensible & easy-to-use but powerful URL shortener. It's created keeping in mind that it should be easy to host and run your custom URL shortener without much effort. [Open-source Python URL shortener]

Expand All @@ -53,7 +47,7 @@ The architecture is very loosely coupled which allows custom integrations easily
- A REST API on top. Uses Flask framework
- The UI layer for rendering the UI. It uses the Django framework

## Features
# Features

- URL shortener
- Customized short URL's(ex: `pygy.co/pygmy`)
Expand All @@ -63,25 +57,25 @@ The architecture is very loosely coupled which allows custom integrations easily
- User dashboard
- Link Analytics(add + to the tiny URL to get link stats)

## Technical Info
# Technical Info

- Python 3, Javascript, JQuery, HTML, CSS
- REST API: Flask
- Pygmyui: Django(It serves the web user interface)
- DB: PostgreSQL/MySQL/SQLite
- Pygmyui: Django(It serves the web user-interface)
- Supported DBs: PostgreSQL/MySQL/SQLite
- Others: SQLAlchmey, JWT
- Docker
- Docker-compose

## Installation/Setup
# Setup

### Docker
## Docker

1. In terminal run this command: `docker pull amit19/pygmy`
2. Then run the container: `docker run -it -p 8000:8000 amit19/pygmy`
3. Open http://localhost:8000 in your browser

### Manual(from source)
## Manual(from source)

1. Clone `git clone https://github.com/amitt001/pygmy.git & cd pygmy`
2. (Optional) Install virtualenv (optional but recommended)
Expand Down Expand Up @@ -110,15 +104,11 @@ Use DB specific instruction below. Make sure to check and modify values in pygmy

### Use MySQL

First, install `pymysql`:

`pip install pymysql`
1. Install pymysql: `pip install pymysql`

Check correct port:
2. Check correct port: `mysqladmin variables | grep port`

`mysqladmin variables | grep port`

Change below line in `pygmy/core/pygmy.cfg`:
3. Change below line in `pygmy/core/pygmy.cfg` file:

```
[database]
Expand All @@ -131,15 +121,13 @@ port: 3306
db_name: pygmy
```

Enter MySQL URL

`CREATE DATABASE pygmy;`
4. Enter MySQL URL `CREATE DATABASE pygmy;`

Note: It's better to use Mysql with version > `5.6.5` to use the default value of `CURRENT_TIMESTAMP` for `DATETIME`.

### Use Postgresql

Change below line in `pygmy/core/pygmy.cfg`:
1. Change below line in `pygmy/core/pygmy.cfg` file:

```
[database]
Expand All @@ -154,9 +142,9 @@ db_name: pygmy

### Use SQLite

SQLite is natively supported in Python
> SQLite is natively supported in Python
`sqlite:////var/lib/pygmy/pygmy.db`
1. Update `sqlite:////var/lib/pygmy/pygmy.db` file

```
[database]
Expand All @@ -167,13 +155,7 @@ sqlite_db_file_name: pygmy.db

## Docker

Docker image name: amit19/pygmy

Docker image can be built by: `docker build -t amit19/pygmy .`

Both the Dockerfile and docker-compose file are present at the root of the project.

To use docker-compose you need to pass DB credentials in the docker-compose file
Docker image name: `amit19/pygmy`. Docker image can be built by running `docker build -t amit19/pygmy .` command. Both the Dockerfile and docker-compose file are present at the root of the project. To use docker-compose you need to pass DB credentials in the docker-compose file.

## Using Pygmy API

Expand All @@ -186,20 +168,9 @@ To use docker-compose you need to pass DB credentials in the docker-compose file
"password": "a_safe_one"
}'


*To be updated soon*

Get User:

Get All User Link:

Create Link:

Get Link:

## Shell Usage

Open shell using ./shell. Available context is pygmy, Config, DB, etc. See all context by using pygmy_context.
Open shell using ./shell. Available context in shell are: pygmy, Config, DB, etc. See all context by using pygmy_context.

Shorten a link:

Expand Down Expand Up @@ -271,15 +242,13 @@ Docstring:
URL value.
```

###### How Link Stats Are Generated?

For getting geo location stats from IP maxminds' [GeoLite2-Country.mmd](http://pygy.co/cm) database is used. It's in `pygmy/app` directory.
Q. How Link Stats Are Generated?
> For getting geo location stats from IP maxminds' [GeoLite2-Country.mmd](http://pygy.co/cm) database is used. It's in `pygmy/app` directory.
###### How Pygmy Auth Token Works?
Q. How Pygmy Auth Token Works?
> It uses JWT. When user logs in using username and password two tokens are generated, refresh token and auth token. Auth token is used for authentication with the Pygmy API. The refresh token can only be used to generate a new auth token. Auth token has a very short TTL but refresh token has a longer TTL. After 30 minutes. When a request comes with the old auth token and a new token is generated from the refresh token API. User passwords are encrypted by [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hash algorithm.
It uses JWT. When user logs in using username and password two tokens are generated, refresh token and auth token. Auth token is used for authentication with the Pygmy API. The refresh token can only be used to generate a new auth token. Auth token has a very short TTL but refresh token has a longer TTL. After 30 minutes. When a request comes with the old auth token and a new token is generated from the refresh token API. User passwords are encrypted by [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) hash algorithm.

## Development
# Development

If you find any bug, have a question or a general feature request. Open an issue on the 'Issue' page.

Expand All @@ -290,42 +259,22 @@ To contribute to the project:
3. Test the changer by running: `docker run -it -p 8000:8000 pygmy`
4. The website will be available at http://127.0.0.1:8000/

Run tests:

Install pytest(`pip install pytest`)
In root directory run this command: `py.test`

Or with coverage report(`pip install coverage`):

`coverage run --omit="*/templates*,*/venv*,*/tests*" -m py.test`

See coverage report(Coverage is bad because the coverage for integration tests is not generated yet):

`coverage report`

## Contributions

Thanks [batarian71](https://github.com/batarian71) for providing the logo icon.

## Donations

I do not run any ads on this project. The server(currently paid by DigitalOcean till Jan 2019) or domain cost, I pay out of my pocket. However, this can't continue forever.

If you find this project helpful, you can help me keep this project running in future by donating any amount you see fit :)

[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.me/amit19)
## Run tests:

## Sponsorship
1. Install pytest (if not already installed): `pip install pytest`
2. In root directory run command: `py.test`

I would like to thank DigitalOcean for providing initial hosting to the Pygmy project. Pygy.co is hosted on DigitalOcean.
#### Run tests with coverage report

<a href="https://www.digitalocean.com/"><img src="https://i.imgur.com/6cYodyH.png"></a>
1. Install coverage `pip install coverage`
2. Run command: `coverage run --omit="*/templates*,*/venv*,*/tests*" -m py.test`
3. See coverage report(Coverage numbers are low as the coverage for integration tests is not generated): `coverage report`

## License
# License

MIT License

Copyright (c) 2017 Amit Tripathi(https://twitter.com/amitt019)
Copyright (c) 2022 Amit Tripathi(https://twitter.com/amitt019)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down

0 comments on commit 88c7c31

Please sign in to comment.