flask-base 0.0.3
A simple Flask boilerplate app with SQLAlchemy, Redis, User Authentication, and more.
License: MIT
Keywords: flask-base flask

flask-base
==========

|python3.x| |python2.x|

.. figure:: https://raw.githubusercontent.com/longniao/flask-base/master/readme_media/logo.png
   :alt: flask-base

   flask-base

A Flask application template with the boilerplate code already done for you.

**Documentation available at http://hack4impact.github.io/flask-base.**

What's included?
----------------

-  Blueprints
-  User and permissions management
-  Flask-SQLAlchemy for databases
-  Flask-WTF for forms
-  Flask-Assets for asset management and SCSS compilation
-  Flask-Mail for sending emails
-  gzip compression
-  Redis Queue for handling asynchronous tasks
-  ZXCVBN password strength checker
-  CKEditor for editing pages

Demos
-----

Home Page:

.. figure:: https://raw.githubusercontent.com/longniao/flask-base/master/readme_media/home.gif
   :alt: home


Registering User:

.. figure:: https://raw.githubusercontent.com/longniao/flask-base/master/readme_media/register.gif
   :alt: register


Admin Editing Page:

.. figure:: https://raw.githubusercontent.com/longniao/flask-base/master/readme_media/editpage.gif
   :alt: editpage


Admin Editing Users:

.. figure:: https://raw.githubusercontent.com/longniao/flask-base/master/readme_media/edituser.gif
   :alt: edituser


Setting up
----------

Clone the repo
''''''''''''''

::

    $ git clone https://github.com/longniao/flask-base.git
    $ cd flask-base

Initialize a virtualenv
'''''''''''''''''''''''

::

    $ pip install virtualenv
    $ virtualenv -p /path/to/python3.x/installation env
    $ source env/bin/activate

For mac users it will most likely be

::

    $ pip install virtualenv
    $ virtualenv -p python3 env
    $ source env/bin/activate

Note: if you are using a python2.x version, point the -p value towards
your python2.x path

(If you're on a mac) Make sure xcode tools are installed
''''''''''''''''''''''''''''''''''''''''''''''''''''''''

::

    $ xcode-select --install

Add Environment Variables
'''''''''''''''''''''''''

Create a file called ``config.env`` that contains environment variables
in the following syntax: ``ENVIRONMENT_VARIABLE=value``. You may also
wrap values in double quotes like
``ENVIRONMENT_VARIABLE="value with spaces"``. For example, the mailing
environment variables can be set as the following. We recommend using
Sendgrid for a mailing SMTP server, but anything else will work as well.

::

    MAIL_USERNAME=SendgridUsername
    MAIL_PASSWORD=SendgridPassword
    SECRET_KEY=SuperRandomStringToBeUsedForEncryption

Other Key value pairs:

-  ``ADMIN_EMAIL``: set to the default email for your first admin
   account (default is ``flask-base-admin@example.com``)
-  ``ADMIN_PASSWORD``: set to the default password for your first admin
   account (default is ``password``)
-  ``DATABASE_URL``: set to a postgresql database url (default is
   ``data-dev.sqlite``)
-  ``REDISTOGO_URL``: set to Redis To Go URL or any redis server url
   (default is ``http://localhost:6379``)
-  ``RAYGUN_APIKEY``: api key for raygun (default is ``None``)
-  ``FLASK_CONFIG``: can be ``development``, ``production``,
   ``default``, ``heroku``, ``unix``, or ``testing``. Most of the time
   you will use ``development`` or ``production``.

**Note: do not include the ``config.env`` file in any commits. This
should remain private.**

Install the dependencies
''''''''''''''''''''''''

::

    $ pip install -r requirements.txt

Other dependencies for running locally
''''''''''''''''''''''''''''''''''''''

You need `Redis <http://redis.io/>`__, and
`Sass <http://sass-lang.com/>`__. Chances are, these commands will work:

**Sass:**

::

    $ gem install sass

**Redis:**

*Mac (using `homebrew <http://brew.sh/>`__):*

::

    $ brew install redis

*Linux:*

::

    $ sudo apt-get install redis-server

You will also need to install **PostgresQL**

*Mac (using homebrew):*

::

    brew install postgresql

*Linux (based on this
`issue <https://github.com/hack4impact/flask-base/issues/96>`__):*

::

    sudo apt-get install libpq-dev

Create the database
'''''''''''''''''''

::

    $ python manage.py recreate_db

Other setup (e.g. creating roles in database)
'''''''''''''''''''''''''''''''''''''''''''''

::

    $ python manage.py setup_dev

Note that this will create an admin user with email and password
specified by the ``ADMIN_EMAIL`` and ``ADMIN_PASSWORD`` config
variables. If not specified, they are both
``flask-base-admin@example.com`` and ``password`` respectively.

[Optional] Add fake data to the database
''''''''''''''''''''''''''''''''''''''''

::

    $ python manage.py add_fake_data

Running the app
---------------

::

    $ source env/bin/activate
    $ honcho start -f Local

For Windows users having issues with binding to a redis port locally,
refer to `this
issue <https://github.com/hack4impact/flask-base/issues/132>`__.

Formatting code
---------------

Before you submit changes to flask-base, you may want to autoformat your
code with ``python manage.py format``.

Contributing
------------

Contributions are welcome! Check out our `Waffle
board <https://waffle.io/hack4impact/flask-base>`__ which automatically
syncs with this project's GitHub issues. Please refer to our `Code of
Conduct <./CONDUCT.md>`__ for more information.

Documentation Changes
---------------------

To make changes to the documentation refer to the `Mkdocs
documentation <http://www.mkdocs.org/#installation>`__ for setup.

To create a new documentation page, add a file to the ``docs/``
directory and edit ``mkdocs.yml`` to reference the file.

When the new files are merged into ``master`` and pushed to github. Run
``mkdocs gh-deploy`` to update the online documentation.

Related
-------

https://medium.freecodecamp.com/how-we-got-a-2-year-old-repo-trending-on-github-in-just-48-hours-12151039d78b#.se9jwnfk5

License
-------

`MIT License <LICENSE.md>`__

.. |Circle CI| image:: https://circleci.com/gh/hack4impact/flask-base.svg?style=svg
   :target: https://circleci.com/gh/hack4impact/flask-base
.. |Stories in Ready| image:: https://badge.waffle.io/hack4impact/flask-base.png?label=ready&title=Ready
   :target: https://waffle.io/hack4impact/flask-base
.. |Code Climate| image:: https://codeclimate.com/github/hack4impact/flask-base/badges/gpa.svg
   :target: https://codeclimate.com/github/hack4impact/flask-base/coverage
.. |Issue Count| image:: https://codeclimate.com/github/hack4impact/flask-base/badges/issue_count.svg
   :target: https://codeclimate.com/github/hack4impact/flask-base
.. |python3.x| image:: https://img.shields.io/badge/python-3.x-brightgreen.svg
.. |python2.x| image:: https://img.shields.io/badge/python-2.x-yellow.svg