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 `_. 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 `_ 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 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 ------------ Development ~~~~~~~~~~~ For development you can create the database with the command below. This will additional to the database also create a few users with some example content. :: python manage.py createall To test if everything has worked, run the development server with ``python manage.py runserver``. Production ~~~~~~~~~~ Now, you can start the installation process with :: python manage.py initflaskbb During the installation process you are asked about your username, your email address and the password for your administrator user. 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-plugins-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/``.