Flask 1: Cài đặt và thiết lập framework Flask

Flask là 1 framework nhỏ bởi hầu hết các tiêu chuẩn, nó đủ nhỏ để được gọi là “micro-framework”. Nó đủ nhỏ để bạn để khi bạn quen thuộc với nó, bạn có thể sẽ đọc và hiểu được tất cả các source code của nó. Nhưng tuy nhỏ cũng không có nghĩa là nó ít hơn so với các framework khác.

Using Virtual Environments

Virtual Environments được tạo với tiện ích virtualenv của bên thứ 3. Để kiểm tra xem bạn đã cài đặt chúng trên hệ thống của bạn với câu lệnh sau:

Code:

virtualenv --version

Nếu có thông báo lỗi, bạn cần phải cài đặt 1 số tiện ích

Các bản phân phối của linux cũng có cung cấp các gói cho virtualenv. Ví dụ trên Ubuntu bạn chỉ cần gõ lệnh sau:

Code:

sudo apt-get install python-virtualenv

Nếu bạn sử dụng OS X thì bạn cần cài đặt virtualenv với easy_install:

Code:

sudo easy_install virtualenv

Nếu bạn sử dụng Window hay hệ điều hành nào mà không hỗ trợ virtualenv, thì công việc cài đặt sẽ khó khăn hơn 1 chút. Bạn phải download file này về https://bootstrap.pypa.io/ez_setup.py và thực hiện 1 số lệnh sau:

Code:

$ python ez_setup.py
$ easy_install virtualenv

Bây giờ bạn cần tạo ra các thư mục để lưu trữ các example code, nó có sẵn từ kho lưu trữ Github. Thực hiện câu lệnh download excample code từ Github và khởi tạo các thư mục ứng dụng với phiên bản “1a”, phiên bản đầu tiên của ứng dụng.

Code:

$ git clonehttps://github.com/miguelgrinberg/flasky.git
$ cd flasky
$ git checkout1a

Tiếp theo là tạo môi trường ảo trên thư mục flasky sử dụng câu lệnh virtualenv. Một thư mục với tên đã được chọn sẽ được tạo ngay trên thư mục hiện hành và tất cả cá tập tin liên kết với các môi trường ảo.

Code:

$virtualenv venv
Newpython executable invenv/bin/python2.7
Also creating executable invenv/bin/python
Installing setuptools............done.
Installing pip...............done.

Bây giờ bạn có 1 thư mục venv bên trong thư mục flasky với 1 môi trường ảo có chứa 1 thông dịch python. Để sử dụng môi trường ảo bạn phải kích hoạt nó. Nếu bạn đang sử dụng Linux, OS X bạn có thể sử dụng lệnh sau:

Code:

source venv/bin/activate

Nếu bạn sử dụng window bạn cần sử dụng câu lênh:

Code:

venv\Scripts\activate

Installing Python Packages with pip

Hầu hết các gói python đều được cài đặt với pip, virtualenv sẽ tự động thêm tất cả vào môi trường ảo. Khi môi trường ảo được kích hoạt thì vị trí của pip sẽ được thêm vào PATH.

Cài đặt Flask cho môi trường ảo sử dụng câu lệnh:

Code:

(venv)$pip install flask

Với câu lệnh, Flask và các gói phụ thuộc sẽ được cài đặt trong môi trường ảo. Bạn cũng có thể xác minh Flask đã được cài đặt thành công bằng cách thử import chúng:

Code:

(venv)$python
>>>import flask
>>>

Nếu không có lỗi thì chắc chắn rằng bạn đã thành công và chuẩn bị sẽ viết những ứng dụng của bạn.

1.1 Python

1.1.1 Check your Python version:

$ python --version 

The output should be:

• 2.6.6 (Debian 6)
• 2.7.3 (Debian 7 and Ubuntu 12.04)

If your version is 2.6.6 (which is the default one on Debian 6), it is recommended that you set up Python 2.7+ in a separate virtual environment.

Debian 7 and Ubuntu 12.04 users who already have Python 2.7+ can jump to SECTION 1.1.6.

1.1.2 Install the build-essential package:

$ sudo apt-get install build-essential

1.1.3 Install some additionnal packages

$ sudo apt-get install zlib1g-dev libssl-dev python-dev

Notes:

• zlib1g and libssl are required for Zlib and SSL support in Python
• python-dev is required if you use Pillow as your Python imaging library (see below SECTION 2.3)

1.1.4 Install Python from source:

$ wget http://www.python.org/ftp/python/2.7.3/Python-2.7.3.tgz
$ tar -xzvf Python-2.7.3.tgz
$ cd Python-2.7.3
$ ./configure --enable-shared --with-threads
$ make
$ sudo make altinstall

Python 2.7.3 should now be installed into the following directories:

• /usr/local/lib/
• /usr/local/bin/

1.1.5 Check if Python executable is finding libpython shared library:

$ ldd /usr/local/bin/python2.7

If you have this line "libpython2.7.so.1.0 => not found" in the output, then you need to add /usr/local/lib to your LD_LIBRARY_PATH:

Create a new file called libpython2.7.conf and paste your path in it (in our case it is "usr/local/lib") :

$ cd /etc/ld.so.conf.d/
$ sudo nano libpython2.7.conf

Paste your Python path in it, e.g.:

usr/local/lib

And run ldconfig:

$ sudo /sbin/ldconfig

Then check again the ldd command above. You should now see "libpython2.7.so.1.0 => /usr/local/lib/libpython2.7.so.1.0".

1.1.6 Set-up a Python virtual environment:

Install pip and virtualenv:

$ sudo apt-get install python-pip
$ sudo pip install --upgrade pip
$ sudo pip install virtualenv

Create a new folder for the loris project in /opt:

$ sudo mkdir /opt/loris
$ cd /opt/loris

(Debian 6 only) Create in the loris folder a virtualenv called "env" with the new version of Python, and then activate it:

// Debian 6
$ sudo virtualenv --python=/usr/local/bin/python2.7 env
$ . env/bin/activate

1.2 Apache Mod_wsgi

Critical info from mod_wsgi documentation: “Note that the version of Python from which this baseline environment is created must be the same version of Python that mod_wsgi was compiled for. It is not possible to mix environments based on different major/minor versions of Python.”

It means that you can't use the default "libapache2-mod-wsgi" from official Debian packages if you're running under a different version of Python (for instance in Debian 6 libapache2-mod-wsgi was compiled for Python 2.6.6, so you can't use it with a Loris instance running under Python 2.7.3). If you're in that case you need to compile and install mod_wsgi from the sources, as you did before for Python.

Debian 7 and Ubuntu 12.04 users can jump to SECTION 1.2.2.

1.2.1 Compile mod_wsgi from source (Debian 6)

Important: note that you need the apache development headers to configure mod_wsgi properly (you will find "apache2-prefork-dev" or "apache2-threaded-dev" in Debian repositories ; you can check which one to use by inspecting the output of "/usr/sbin/apachectl -V").

$ wget http://modwsgi.googlecode.com/files/mod_wsgi-3.4.tar.gz
$ tar -xvfz mod_wsgi-3.4.tar.gz
$ cd mod_wsgi-3.4/
$ ./configure --with-apxs=/usr/bin/apxs2 --with-python=/opt/loris/env/bin/python2.7
$ make 
$ sudo make install

Check if the module is ok:

$ ldd /usr/lib/apache2/modules/mod_wsgi.so

You should have the line "libpython2.7.so.1.0 => /usr/local/lib/libpython2.7.so.1.0".

Load the module into Apache:

$ cd /etc/apache2/mods-available
$ sudo nano wsgi.load

Add this line to the file wsgi.load:

LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so

1.2.2 Activate the wsgi module:

// Only for Debian 7 / Ubuntu 12.04
$ sudo apt-get install libapache2-mod-wsgi

// for everyone
$ sudo a2enmod wsgi
$ sudo /etc/init.d/apache2 reload

2. Loris dependencies

2.1 Werkzeug

// Debian 6
$ cd /opt/loris/env
$ sudo bin/pip install Werkzeug

// Debian 7 / Ubuntu 12.04
$ sudo pip install Werkzeug

2.2 Kakadu

Download and install the Kakadu binaries:

$ cd /usr/local/lib/
$ sudo wget https://github.com/sul-dlss/Djatoka/raw/master/lib/Linux-x86-32/libkdu_v60R.so

$ cd /usr/local/bin
$ sudo wget https://github.com/sul-dlss/Djatoka/raw/master/bin/Linux-x86-32/kdu_expand

Note: if you're running a 64-bit OS, you can try an upper version of Kakadu (7.2) (works in Ubuntu 12.04 64-bit) : http://www.kakadusoftware.com/executables/

Run this command into the terminal:

$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

Check if kdu_expand is executing:

$ /usr/local/bin/kdu_expand -v
This is Kakadu's "kdu_expand" application.
        Compiled against the Kakadu core system, version v6.0
        Current core system version is v6.0

2.3 Python Imaging Library (PIL or Pillow)

Pillow is recommended by the Loris documentation. According to the Pillow documentation, Pillow (instead of PIL) is already included in the Debian/Ubuntu distributions, but it seems to be true only since Ubuntu 13.04 (see python-imaging package) and only in Debian "sid" unstable version (see the new python-pil package).

PIL or Pillow have to be built/installed after Little CMS, so you need to remove them first if you already have them:

$ cd /opt/loris/env
$ sudo bin/pip uninstall PIL
$ sudo bin/pip uninstall Pillow
$ sudo apt-get purge python-imaging

Install all the dependencies:

// Debian 6
$ sudo apt-get install libjpeg62 libjpeg62-dev libjpeg8 libjpeg8-dev libfreetype6 libfreetype6-dev zlib1g zlib1g-dev liblcms-dev liblcms-utils libtiff4-dev

// Debian 7
$ sudo apt-get install libjpeg8 libjpeg8-dev libfreetype6 libfreetype6-dev zlib1g-dev liblcms liblcms-dev liblcms-utils libtiff4-dev

A. Install Pillow

$ sudo bin/pip install Pillow

Check if the dependencies are met:

[...]
--- ZLIB (PNG/ZIP) support available
--- TIFF G3/G4 (experimental) support available
--- FREETYPE2 support available
--- LITTLECMS support available
[...]

B. Install PIL

The problem with PIL is the same as mod_wsgi: you can't use the Debian 6 package and need to build it from source if you're using a different version of Python.

Check which Python version the Debian package was compiled for:

$ apt-cache show python-imaging

If the dependency is python2.6, let's compile our own for Python 2.7 (required for Debian 6):

$ wget http://effbot.org/media/downloads/Imaging-1.1.7.tar.gz
$ tar -xzvf Imaging-1.1.7.tar.gz
$ cd Imaging-1.1.7/
$ sudo /opt/loris/env/bin/python2.7 setup.py install

Check the dependencies:

--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available

If you're on Debian 7 /  Ubuntu 12.04 only, just install the python-imaging package:

$ sudo apt-get install python-imaging

3. Loris setup

3.1 Download Loris

Clone Loris from Github repository (wherever you want, e.g. in your home directory):

$ git clone https://github.com/pulibrary/loris.git

3.2 Test, configure and install

Run the tests:

$ cd loris
// Debian 6
$ sudo /opt/loris/env/bin/python2.7 test.py
// Debian 7
$ sudo ./test.py

If the tests are passed, then you should configure Loris to meet your own needs (see the page Configuration and options for the details). Especially you should pay attention to the user and group under which Loris will be running and set various system paths (www and cache directories, root directory for images, path to kdu_expand binary...). You may also want to set your own CORS whitelist or set it to "*".

Edit loris.conf to reflect your needs :

$ nano etc/loris.conf

Add a new user/group for the Loris application:

$ sudo useradd -d /var/www/loris -s /sbin/false loris

Run the install script:

// Debian 6
$ sudo /opt/loris/env/bin/python2.7 setup.py install
// Debian 7 / Ubuntu 12.04
$ sudo ./setup.py install

You should see a success message and a summary of your configuration options.

If you just want to test Loris and don't have your own images, copy the contents of the "tests/img" folder into your "src_img_root" (by default it is set to "/usr/local/share/images", so you need to create it if you didn't set your own).

Go to the loris folder (depending on where you cloned it before, e.g. into your home):

$ cd /home/username/loris

Copy the sample images into your src_img_root:

$ sudo cp -R tests/img/* /usr/local/share/images/

For Debian 6 only: edit the WSGI file (e.g. /var/www/loris/loris.wsgi) in order to have the following content:

import site;
site.addsitedir('/opt/loris/env/lib/python2.7/site-packages')

from loris.webapp import create_app
application = create_app()

4. Deploy with Apache

Important: note that you can't use mod_wsgi and mod_python at the same time (unless you recompile mod_python to use the same version of Python that mod_wsgi is using ; see this section of mod_wsgi documentation for more details).

So you may need to disable mod_python:

$ sudo a2dismod python

Then add the following directives to your virtualhost configuration file (adjust if needed):

ExpiresActive On
ExpiresDefault "access plus 5184000 seconds"
AllowEncodedSlashes On
WSGIDaemonProcess loris user=loris group=loris processes=10 threads=15 maximum-requests=10000
WSGIScriptAlias /loris /var/www/loris/loris.wsgi
WSGIProcessGroup loris

And enable the required modules:

$ sudo a2enmod headers expires
$ sudo /etc/init.d/apache2 reload

5. Check your installation

Have a look at http://{your_server}/loris/.
If the appropriate message is being displayed, you could check some of the sample IIIF URLs pointing to the images you previously put in your "src_img_root":

• http://{your_server}/loris/01/02/0001.jp2/full/full/0/native.jpg (jpeg2000)
• http://{your_server}/loris/01/03/0001.jpg/full/full/0/native.jpg (jpeg)
• http://{your_server}/loris/01/04/0001.tif/full/full/0/native.jpg (tiff)

If you're facing some troubles with mod_wsgi, have a look at this page : http://code.google.com/p/modwsgi/wiki/CheckingYourInstallation

Important: if you're using slashes in the identifier slot (as in the above examples, e.g. "01/04/0001.tif" which is the identifier of the image as defined in IIIF Image API) and if you're running your web server behind a reverse proxy, you should make sure that the AllowEncodedSlashes Apache directive is allowed by the reverse proxy.

If your web server is accessible over the Internet, you can check the IIIF implementation provided by Loris with the IIIF validator:http://iiif-test.stanford.edu (the Image ID should be the filename of the test image in your "src_image_root", e.g. "67352ccc-d1b0-11e1-89ae-279075081939.jp2").