flaskbb/docs/installation.rst

Installation
============

-  `Basic Setup <#basic-setup>`_
-  `Configuration <#configuration>`_
-  `Deplyoing <#deploying>`_



Basic Setup
-----------

Virtualenv Setup
~~~~~~~~~~~~~~~~

Before you can start, you need to create a `virtualenv`.
You can install the virtualenvwrapper with your package manager or via pip.
Be sure that pip is installed. If you don't know how to install pip, have a
look at their `documentation <http://www.pip-installer.org/en/latest/installing.html>`_.

For example, on archlinux you can install it with
::

    $ sudo pacman -S python2-virtualenvwrapper

or, if you own a Mac, you can simply install it with
::

    $ sudo pip install virtualenvwrapper

For more information checkout the  `virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/install.html#basic-installation>`_ installation.

After that you can create your virtualenv with
::

    $ mkvirtualenv -a /path/to/flaskbb -p $(which python2) flaskbb

and you should be switched automatically to your newly created virtualenv.
To deactivate it you just have to type ``deactivate`` and if you want to work
on it again, you need to type ``workon flaskbb``.


Required Dependencies
~~~~~~~~~~~~~~~~~~~~~

Now you can install the required dependencies.
::

    $ pip install -r requirements.txt

Alternatively, you can use the `make` command to install the dependencies.
::

    $ make dependencies


Optional Dependencies
~~~~~~~~~~~~~~~~~~~~~~

We have one optional dependency, redis (the python package is installed automatically).
If you want to use it, be sure that a redis-server is running. If you decide
to use redis, the `online guests` and `online users` are being tracked by redis,
else it will only track the `online users` via a simple SQL query.

**On Archlinux**
::

    # Install redis
    $ sudo pacman -S redis

    # Check if redis is already running.
    $ systemctl status redis

    # If not, start it.
    $ sudo systemctl start redis

    # Optional: Start redis everytime you boot your machine
    $ sudo systemctl enable redis

**On Debian 7.0 (Wheezy)**
::

    # Install redis
    $ sudo apt-get install redis-server

    # Check if redis is already running.
    $ service redis-server status

    # If not, start it
    $ sudo service redis-server start

    # Optional: Start redis everytime you boot your machine
    # I can't remember if this is done automatically..
    $ sudo update-rc.d redis-server defaults


Configuration
-------------

Before you can start, you need to configure `FlaskBB`.


Development
~~~~~~~~~~~

For development, you need to copy ``flaskbb/configs/development.py.example`` to
``flaskbb/configs/development.py``.
::

    cp flaskbb/configs/development.py.example flaskbb/configs/development.py

The reCAPTCHA keys should work fine on localhost.


Production
~~~~~~~~~~

If you plan, to use `FlaskBB` in a production environment (not recommended at
the moment, because it's still in development), you need to copy
``flaskbb/configs/production.py.example`` to ``flaskbb/configs/production.py``.
::

    cp flaskbb/configs/production.py.example flaskbb/configs/production.py

Now open ``flaskbb/configs/production.py`` with your favourite editor and adjust
the config variables to your needs.


Mail Examples
~~~~~~~~~~~~~

Both methods are included in the example configs.

**Google Mail**
::

    MAIL_SERVER = "smtp.gmail.com"
    MAIL_PORT = 465
    MAIL_USE_SSL = True
    MAIL_USERNAME = "your_username@gmail.com"
    MAIL_PASSWORD = "your_password"
    MAIL_DEFAULT_SENDER = ("Your Name", "your_username@gmail.com")

**Local SMTP Server**
::

    MAIL_SERVER = "localhost"
    MAIL_PORT = 25
    MAIL_USE_SSL = False
    MAIL_USERNAME = ""
    MAIL_PASSWORD = ""
    MAIL_DEFAULT_SENDER = "noreply@example.org"


Installation
------------

For a guided install, run
::

    $ make install

or:

    python manage.py install

During the installation process you are asked about your username,
your email address and the password for your administrator user. Using the 
`make install` command is recommended as it checks that the dependencies are also
installed.


Upgrading
---------

If the database models changed after a release, you have to run the ``upgrade``
command
::

    python manage.py db upgrade


Deploying
---------

I prefer to use supervisor, uWSGI and nginx to deploy my apps, but if you have
figured out how to deploy it in another way, please let me know, so I
(or you if you create a pull request) can add it to the documentation.

**NOTE:** I have only used Debian to deploy it, if someone is using a other
distribution, could you let me know if that works too? `Also, if you have better
configurations for uWSGI, supervisor or nginx let me know that too.`


Supervisor
~~~~~~~~~~

`Supervisor is a client/server system that allows its users to monitor and
control a number of processes on UNIX-like operating systems.`

To install `supervisor` on Debian, you need to fire up this command:
::

    $ sudo apt-get install supervisor

There are two ways to configure supervisor. The first one is, you just put
the configuration to the end in the ``/etc/supervisor/supervisord.conf`` file.

The second way would be to create a new file in the ``/etc/supervisor/conf.d/``
directory. For example, such a file could be named ``uwsgi.conf``.

After you have choosen the you way you like, simply put the snippet below in the
configuration file.

::

    [program:uwsgi]
    command=/usr/bin/uwsgi --emperor /etc/uwsgi/apps-enabled
    user=apps
    stopsignal=QUIT
    autostart=true
    autorestart=true
    redirect_stderr=true


uWSGI
~~~~~

`uWSGI is a web application solution with batteries included.`

To get started with uWSGI, you need to install it first.
You'll also need the python plugin to serve python apps.
This can be done with:

::

    $ sudo apt-get install uwsgi uwsgi-plugin-python

For the configuration, you need to create a file in the
``/etc/uwsgi/apps-available`` directory. In this example, I will call the
file ``flaskbb.ini``. After that, you can start with configuring it.
My config looks like this for `flaskbb.org` (see below). As you might have noticed, I'm
using a own user for my apps whose home directory is located at `/var/apps/`.
In this directory there are living all my Flask apps.

::

    [uwsgi]
    base = /var/apps/flaskbb
    home = /var/apps/.virtualenvs/flaskbb/
    pythonpath = %(base)
    socket = 127.0.0.1:30002
    module = wsgi
    callable = flaskbb
    uid = apps
    gid = apps
    logto = /var/apps/flaskbb/logs/uwsgi.log
    plugins = python


===============  ==========================  ===============
**base**         /path/to/flaskbb            The folder where your flaskbb application lives
**home**         /path/to/virtualenv/folder  The virtualenv folder for your flaskbb application
**pythonpath**   /path/to/flaskbb            The same as base
**socket**       socket                      This can be either a ip or the path to a socket (don't forget to change that in your nginx config)
**module**       wsgi.py                     This is the file located in the root directory from flaskbb (where manage.py lives).
**callable**     flaskbb                     The callable is application you have created in the ``wsgi.py`` file
**uid**          your_user                   The user who should be used. **NEVER** use root!
**gid**          your_group                  The group who should be used.
**logto**        /path/to/log/file           The path to your uwsgi logfile
**plugins**      python                      We need the python plugin
===============  ==========================  ===============

Don't forget to create a symlink to ``/etc/uwsgi/apps-enabled``.

::

    ln -s /etc/uwsgi/apps-available/flaskbb /etc/uwsgi/apps-enabled/flaskbb


nginx
~~~~~

`nginx [engine x] is an HTTP and reverse proxy server,
as well as a mail proxy server, written by Igor Sysoev.`

The nginx config is pretty straightforward. Again, this is how I use it for
`FlaskBB`. Just copy the snippet below and paste it to, for example
``/etc/nginx/sites-available/flaskbb``.
The only thing left is, that you need to adjust the ``server_name`` to your
domain and the paths in ``access_log``, ``error_log``. Also, don't forget to
adjust the paths in the ``alias`` es, as well as the socket adress in ``uwsgi_pass``.

::

    server {
        listen 80;
        server_name forums.flaskbb.org;

        access_log /var/log/nginx/access.forums.flaskbb.log;
        error_log /var/log/nginx/error.forums.flaskbb.log;

        location / {
            try_files $uri @flaskbb;
        }

        # Static files
        location /static {
           alias /var/apps/flaskbb/flaskbb/static/;
        }

        location ~ ^/_themes/([^/]+)/(.*)$ {
            alias /var/apps/flaskbb/flaskbb/themes/$1/static/$2;
        }

        # robots.txt
        location /robots.txt {
            alias /var/apps/flaskbb/flaskbb/static/robots.txt;
        }

        location @flaskbb {
            uwsgi_pass 127.0.0.1:30002;
            include uwsgi_params;
        }
    }


Like in the `uWSGI <#uwsgi>`_ chapter, don't forget to create a symlink to
``/etc/nginx/sites-enabled/``.