Install Picly Beta 2.4

Introduction

Picly is developed with Node JS. Its installation is easy as you can see in the following sections.

Current version of Picly (beta 2.4) is for non commercial use.

We work hard to release first production version in the coming weeks.

We want to hear you!

Please use our contact and support form or mail to info@picly.io with and feedback or suggestion.

For any support question, you can mail to support@picly.io

Before You Start

Picly has a few dependecies like Redis, Graphics Magick, OpenCV, and so on. In order to install them you have two options: a script included in the beta 2.4 package or to install each dependency manually.

Option 1: By script

Create Picly folder

$ mkdir picly && cd picly

Download beta 2.4 package

$ wget https://picly.blob.core.windows.net/piclydownloads/picly-f43705ff-beta25.tar

Untar code

$ tar -xvf picly-xxxxxxxx-betaXX.tar

Remove tar file

$ rm picly-xxxxxxxx-betaXX.tar

Once you have the files, you can execute the script:

./install_picly_dependencies.sh

Option 2: Step by step

If you want install each dependencies step by step, here you have the following instructions.

You need install them firstly Node:

NodeJS 8.11.2 LTS:

Picly is fully tested with NodeJS 8.11.2 LTS version.

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

More info at Node JS.

Redis 4+ or 3.4+:

The suggested way of installing Redis is the following:

$ wget https://download.redis.io/redis-stable.tar.gz
tar xvzf redis-stable.tar.gz
cd redis-stable
make

More info at Redis website.

Graphics Magick:

GM is on the most use graphics manipulations library. You can install it in Ubuntu systems with:

$ sudo apt-get update
sudo apt-get install -y graphicsmagick

More info at Graphics Magick

Image Magick:

IM is another popular graphics library used by Picly plugins as well. You can install it in Ubuntu systems with:

$ sudo apt-get install -y imagemagick

More info at Image Magick

Cairo library:

Cairo is an open source graphics library used by some default Picly plugins. To install it:

$ sudo apt-get install -y libcairo2-dev libjpeg-dev libpango1.0-dev libgif-dev build-essential g++

More info at Cairo

Open CV:

Open source library with hundreds of algorithm to analyze images. Again, in Ubuntu systems, you can install it with:

sudo apt-get install -y libopencv-dev

More info at Open CV website

node-gyp package:

As easy as in Ubuntu systems:

sudo npm i -g node-gyp

More info at Node.js native addon build tool

Installation

Inside of picly directory you have made previously you need enter the following command to install and compile Node JS dependencies

$ npm install

Note: this install process can take some time to complete and some warnings can be shown.

License

In order to get your license, just:

$ npm run update-license

Note

Picly Beta 2.4 version is free for non commercial use. Pro and Business version will be released soon. Any question about this? Ask to info@picly.io

Last, check dependencies:

$ npm run check-dependencies

With this command, Picly checks all dependencies are fine.

Start Picly servers

Picly has been developed using microservices architecture to allow an easy installation and easy scalation from a single server to multiple servers.

For running Picly in a single server just type the url and the port where your server will be listening:

$ npm run startsingleserver 192.168.1.103 8000

We are based on 'convention over configuration' premise so... that's all! There is no need edit your config.json to start but, of course, you can change your config later (see config section in 'Documentation').

Note

Note that this action will replace the URL and port entered into your config.json, so there is no need to type the same url and port later. To start with the same parameters is enough with:

npm run startsingleserver

Note

It's valid to enter the server URL as 'localhost' and the port is an optional parameter (by default, the port is 8088).

Open Admin Web Panel

Open your browser and enter the URL and port according you put them as parameters before.

Enter as default user is "admin". Default password is "admin"

Now you have your own images server with on the fly transformations using Picly url syntax!

Up & running with PM2 tool

PM2 Picly installation

Alternatively, instead of 'npm run' you can use PM2 process manager to run Picly installation.

For single server, using PM2 tool, start Picly is as easy as:

$ pm2 start picly_singleserver.js 192.168.1.103 8000

In multiserver mode, Picly is composed by five node servers:

  • Admin Web Panel Server, located at /picly_web/picly_webserver.js
  • Picly API Server, located at /picly_api/picly_apiserver.js
  • Picly Provider Server Server, located at /picly_provider/picly_providerserver.js
  • Picly Background Server, located at /picly_background/picly_backgroundserver.js
  • Public API Picly Server, located at /picly_publicapi/picly_publicapiserver.js

You can run your Picly installation by these commands:

$ pm2 start picly_web/picly_webserver.js
$ pm2 start picly_api/picly_apiserver.js
$ pm2 start picly_provider/picly_providerserver.js
$ pm2 start picly_background/picly_backgroundserver.js
$ pm2 start picly_publicapi/picly_publicapiserver.js

What?

What's a Picly?

One Picly is an image that has been one or more transformations and it has been saved in the system.

This last point is important as is the diference between a simple request and 'Picly'.

What is the limit of transformations?

Infinites. You can do every transformation as you want, again and again. When you get the desired result, you must click over 'Create Picly' then. In this way, the image is stored in the system.

Note

For the free version there is a limit of 6000 Piclys.

Where?

Ok, I have Picly installed, where do I begin?

Basically, everything can resume it in three steps:

  • 1 Upload image

    For that, go to the "Upload" menu option. You can either upload a file from file system or enter the url directly. Keep in mind that every image you upload will take part of your repository.

  • 2 Transform

    Once you added the images, go to any of them to start to transform it. You'll see the basic information about it and a large button called "Lab". Click over it, it's time to talk about "laboratory".

    The laboratory is the place where you can experience with the plugins and unleash your imagination. Please, feel free to doing and undo until you get the desired result. Remember that you can apply as many plugins (you have a detailled information about each plugin in the 'Plugins' menu option) as you want.

    Note

    You must keep in mind that the order matters at the time of apply the plugins. For example, if the request is: "/resize:h(500)/tiny", the first applied transformation is 'resize' and later 'tiny'. In most of cases this doesn't matter but it can be any combination where it was important.

    Note

    As it say before, the number of transformations is unlimited but a they have a short life and it will be erased from the system. Therefore, its use is not suitable for production purposes.

  • 3 Create Picly

    In order to get the transformed image into your system, click over 'Create Picly' and you have it forever. Congrats! you can stop call it an image, transformation or whatever... simply call it 'Picly'.

    A Picly has a 'long' url where shows every plugin used and another shorter. Any of them can be used whatever you want.

    Note

    In opposite of the transformations, Piclys never are erased from the system until you delete it explicitly.

How?

How works the tags system?

An image has information asociated to the image itself such as size, date of creation... Based on this idea, you can add any tag you want over the image (or delete it) for identify and search it later.

It's also a good method to get related images easily and improve the organization.

It is the same system that the blogs have for categorize their publications.

How I search an image?

If you put a tag over a image is very easy its searching. It is enough with go to the Search input and enter the tag.

How I search a Picly?

Generally, you can locate it through its original image.

How works 'Quickly Picly'?

If you already know the id of an image (the last part of the long url or in the info section) you can create directly a Picly. In this case, you need to edit the parameters and without the possibily of obtain a preview, simply create the Picly.

In the same way that you get in the laboratory, here you will find a short url associated to the newly created Picly.

How I can change my configuration?

You have two options to edit the configuration: touching the config.json directly or using the interface of Picly. We know that changing the config.json can be a little bit tough, so we strongly encourge that you do it through the UI.

By default, this is the displayed configuration:

Note

This URL is the location where the browser goes to search the element it want. In other words, it's the 'place' where Picly is listening. It can be a local IP, IP from a Lan or public IP.

Note

In 'files location', values like "/home/~/piclyfiles" are not allowed.

In case you have a license, the configuration appears different and it allows set multi server configuration up.

In both modes, there are new atributes like 'Backups location' or 'Public API port' because only the licensed user have access to them.

In the multi server mode we can change other attributes besides, like URL of provider server and port and so on. In this case, any server URL must not match each other.

Overview

As the public API is restricted to licensed users, it's mandatory to pass a token parameter in order to check whether the request is valid or not.

For that, the first method to learn to use is getToken explained below.

getToken

POST

It gets the token which is needed to work with the public API. Once you obtain the token, you must pass it as a parameter in every request.

Input

Key
APIKey
Value
22e596e3faf11b1222e596e67ea9673faf11b16
{
    APIKey: 22e596e3faf11b1222e596e67ea9673faf11b16
}

Output

A JSON object with this content:

Key
token
Value
BJPGf8Bdf
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps
}

Images

getTotalImages

POST

It obtains the total number of images in the system.

Input

Key
token
Value
xMjIyZTU5NmU2N2VhO...
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps
}

Output

A JSON object with this content:

Key
totalimages
Value
10
{
    totalimages: 10
}

getImages

POST

It obtains the images in the system in a paginated way.

Input

Key
token
page
count
Value
xMjIyZTU5NmU2N2VhO...
0
10
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps
    page: 0,
    count: 10
}

Output

An array of JSON objects (10 in this example) like this:

Key
id
entityname
creation
width
heigth
size
format
Value
BJPGf8Bdf
girl_BJPGf8Bdf
1519899150847
256
256
86949
png
[ {
    id: BJPGf8Bdf,
    entityname: girl_BJPGf8Bdf.png,
    creation: 1519899150847,
    width: 256,
    heigth: 256,
    size: 86949,
    format: png
} ... ]

deleteImage

POST

It deletes an image from the system. Be careful! This action also removes every Picly associated to that image.

Input

Key
token
imageid
Value
xMjIyZTU5NmU2N2VhO...
rJwOcjqdG
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    imageid: rJwOcjqdG
}

Output

A JSON object with this content:

Key
success
message
Value
false
Error deleting image
{
    success: true
    message: ""
}
{
    sucess: false,
    message: Error deleting image
}

Piclys

getTotalPiclys

POST

It obtains the total number of Piclys in the system.

Input

Key
token
Value
xMjIyZTU5NmU2N2VhO...
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps
}

Output

A JSON object with this content:

Key
totalpiclys
Value
10
{
    totalpiclys: 10
}

createPicly

POST

It creates a new Picly. If the Picly is already created, simply return its id.

Input

Key
token
request
message
Value
xMjIyZTU5NmU2N2VhO...
/resize:w(320)/rJwOcjqdG
""
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    request: /resize:w(320)/rJwOcjqdG
}

Output

A JSON object with this content:

Key
success
shortrequestid
Value
true
HJeBAyn-G
{
    success: true,
    shortrequestid: HJeBAyn-G
}
{
    success: false,
    shortrequestid: "",
    message: Error creating picly
}

deletePicly

POST

It deletes a Picly from the system.

Input

Key
token
requestid
Value
xMjIyZTU5NmU2N2VhO...
1500d00c19d7cde627396840fbeafed5
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    requestid: 1500d00c19d7cde627396840fbeafed5
}

Output

A JSON object with this content:

Key
success
message
Value
true
""
{
    success: true,
    message: ""
}
{
    success: false,
    message: Error deleting picly
}

getPiclysOfImage

POST

It obtains all Piclys associated to an image.

Input

Key
token
imageid
Value
MjIyZTU5NmU2N2VhO...
rJwOcjqdG
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    imageid: rJwOcjqdG
}

Output

A JSON object with this content:

Key
requestid
originalimageid
creation
requesturl
shortrequestid
Value
1500d00c19d7cde627396840fbeafed5
rJwOcjqdG
1520332010700
/resize:w(320)/rJwOcjqdG
HJeBAyn-G
{
    requestid: 1500d00c19d7cde627396840fbeafed5,
    originalimageid: rJwOcjqdG,
    creation: 1520332010700,
    requesturl: /resize:w(320)/rJwOcjqdG,
    shortrequestid: HJeBAyn-G
}

Upload

uploadByUrl

POST

It uploads an image to the system through its URL directly.

Input

Key
token
url
Value
xMjIyZTU5NmU2N2VhO...
https://www.images.com/sample.jpg
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    url: https://www.images.com/sample.jpg
}

Output

A JSON object with this content:

Key
imageid
filename
success
message
Value
BJPGf8Bdf
girl_BJPGf8Bdf.png
true
""
{
    imageid: BJPGf8Bdf,
    filename: girl_BJPGf8Bdf.png,
    success: true,
    message: ""
}
{
    imageid: BJPGf8Bdf,
    filename: girl_BJPGf8Bdf.png,
    success: false,
    message: Image duplicated
}

newUpload

POST

It starts an image upload to the system. It returns a code to identify the upload process.

Input

Key
token
filename
filesize
Value
xMjIyZTU5NmU2N2VhO...
https://www.images.com/sample.jpg
55
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    filename: htts://www.images.com/sample.jpg,
    filesize: ""
}

Output

A JSON object with this content:

Key
uploadid
Value
BJPGf8Bdf
{
    uploadid: BJPGf8Bdf
}

completeUpload

POST

It indicates the finish of the upload of the blocks.

Input

Key
token
uploadid
Value
xMjIyZTU5NmU2N2VhO...
""
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    uploadid: ""
}

Output

A JSON object with this content:

Key
success
imageid
filename
message
Value
true
id
new_image.jpg
""
{
    result: true,
    imageid: id,
    filename: new_image.jpg,
    message: ""
}
{
    result: false,
    imageid: id,
    filename: new_image.jpg,
    message: Error when uploading image
}

newChunk

POST

It adds a new block to the file that is uploading.

Input

Key
token
chunkBuffer
chunkNumber
chunkSize
uploadid
Value
xMjIyZTU5NmU2N2VhO...
chunk
0
15486
1
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps,
    chunkBuffer: chunk,
    chunkNumber: 0,
    chunkSize: 15486,
    uploadid: id
}

Output

A JSON object with this content:

Key
result
Value
BJPGf8Bdf
{
    result: true,
}

Example of upload

Here you find an example of use where it shows how upload an image using the methods explained above.

Others

getPlugins

POST

It obtains all the plugins registered in the system.

Input

Key
token
Value
xMjIyZTU5NmU2N2VhO...
{
    token: xMjIyZTU5NmU2N2VhOTY3M2ZhZjExYjEyIiwiaWF0IjoxNTE5OTAyMTg2LCJleHAiOjE1MTk5ODg1ODZ9.fYGFujkbeGF1vDsZ7N5aH0Pp_ug0Y3f4bayIschOjps
}

Output

An array of JSONs which have this content:

Key
name
info
Value
BJPGf8Bdf
Picly module for apply aging effect
[
{
    name: aging,
    info: Picly module for apply agning effect
},
...
]