Quick Start
***********

* Basic SQLAlchemy Application

* Basic SQLAlchemy Application with session

* Basic MongoEngine Application

* Basic Peewee Application

* Mail Configuration

* Proxy Configuration


Basic SQLAlchemy Application
****************************


SQLAlchemy Install requirements
===============================

   $ mkvirtualenv <your-app-name>
   $ pip install flask-security flask-sqlalchemy


SQLAlchemy Application
======================

The following code sample illustrates how to get started as quickly as
possible using SQLAlchemy:

   from flask import Flask, render_template
   from flask_sqlalchemy import SQLAlchemy
   from flask_security import Security, SQLAlchemyUserDatastore, \
       UserMixin, RoleMixin, login_required

   # Create app
   app = Flask(__name__)
   app.config['DEBUG'] = True
   app.config['SECRET_KEY'] = 'super-secret'
   app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite://'

   # Create database connection object
   db = SQLAlchemy(app)

   # Define models
   roles_users = db.Table('roles_users',
           db.Column('user_id', db.Integer(), db.ForeignKey('user.id')),
           db.Column('role_id', db.Integer(), db.ForeignKey('role.id')))

   class Role(db.Model, RoleMixin):
       id = db.Column(db.Integer(), primary_key=True)
       name = db.Column(db.String(80), unique=True)
       description = db.Column(db.String(255))

   class User(db.Model, UserMixin):
       id = db.Column(db.Integer, primary_key=True)
       email = db.Column(db.String(255), unique=True)
       password = db.Column(db.String(255))
       active = db.Column(db.Boolean())
       confirmed_at = db.Column(db.DateTime())
       roles = db.relationship('Role', secondary=roles_users,
                               backref=db.backref('users', lazy='dynamic'))

   # Setup Flask-Security
   user_datastore = SQLAlchemyUserDatastore(db, User, Role)
   security = Security(app, user_datastore)

   # Create a user to test with
   @app.before_first_request
   def create_user():
       db.create_all()
       user_datastore.create_user(email='matt@nobien.net', password='password')
       db.session.commit()

   # Views
   @app.route('/')
   @login_required
   def home():
       return render_template('index.html')

   if __name__ == '__main__':
       app.run()


Basic SQLAlchemy Application with session
*****************************************


SQLAlchemy Install requirements
===============================

   $ mkvirtualenv <your-app-name>
   $ pip install flask-security sqlalchemy

Also, you can use the extension Flask-SQLAlchemy-Session
documentation.


SQLAlchemy Application
======================

The following code sample illustrates how to get started as quickly as
possible using SQLAlchemy in a declarative way:

We are gonna split the application at least in three files: app.py,
database.py and models.py. You can also do the models a folder and
spread your tables there.

* app.py

::
   from flask import Flask from flask_security import Security,
   login_required,

      SQLAlchemySessionUserDatastore

   from database import db_session, init_db from models import User,
   Role

   # Create app app = Flask(__name__) app.config['DEBUG'] = True
   app.config['SECRET_KEY'] = 'super-secret'

   # Setup Flask-Security user_datastore =
   SQLAlchemySessionUserDatastore(db_session,

      User, Role)

   security = Security(app, user_datastore)

   # Create a user to test with @app.before_first_request def
   create_user():

      init_db() user_datastore.create_user(email='matt@nobien.net',
      password='password') db_session.commit()

   # Views @app.route('/') @login_required def home():

      return render('Here you go!')

   if __name__ == '__main__':
      app.run()

* database.py

::
   from sqlalchemy import create_engine from sqlalchemy.orm import
   scoped_session, sessionmaker from sqlalchemy.ext.declarative import
   declarative_base

   engine = create_engine('sqlite:////tmp/test.db',
      convert_unicode=True)

   db_session = scoped_session(sessionmaker(autocommit=False,
      autoflush=False, bind=engine))

   Base = declarative_base() Base.query = db_session.query_property()

   def init_db():
      # import all modules here that might define models so that #
      they will be registered properly on the metadata.  Otherwise #
      you will have to import them first before calling init_db()
      import models Base.metadata.create_all(bind=engine)

* models.py

::
   from database import Base from flask_security import UserMixin,
   RoleMixin from sqlalchemy import create_engine from sqlalchemy.orm
   import relationship, backref from sqlalchemy import Boolean,
   DateTime, Column, Integer,

      String, ForeignKey

   class RolesUsers(Base):
      __tablename__ = 'roles_users' id = Column(Integer(),
      primary_key=True) user_id = Column('user_id', Integer(),
      ForeignKey('user.id')) role_id = Column('role_id', Integer(),
      ForeignKey('role.id'))

   class Role(Base, RoleMixin):
      __tablename__ = 'role' id = Column(Integer(), primary_key=True)
      name = Column(String(80), unique=True) description =
      Column(String(255))

   class User(Base, UserMixin):
      __tablename__ = 'user' id = Column(Integer, primary_key=True)
      email = Column(String(255), unique=True) username =
      Column(String(255)) password = Column(String(255)) last_login_at
      = Column(DateTime()) current_login_at = Column(DateTime())
      last_login_ip = Column(String(100)) current_login_ip =
      Column(String(100)) login_count = Column(Integer) active =
      Column(Boolean()) confirmed_at = Column(DateTime()) roles =
      relationship('Role', secondary='roles_users',

         backref=backref('users', lazy='dynamic'))


Basic MongoEngine Application
*****************************


MongoEngine Install requirements
================================

   $ mkvirtualenv <your-app-name>
   $ pip install flask-security flask-mongoengine


MongoEngine Application
=======================

The following code sample illustrates how to get started as quickly as
possible using MongoEngine:

   from flask import Flask, render_template
   from flask_mongoengine import MongoEngine
   from flask_security import Security, MongoEngineUserDatastore, \
       UserMixin, RoleMixin, login_required

   # Create app
   app = Flask(__name__)
   app.config['DEBUG'] = True
   app.config['SECRET_KEY'] = 'super-secret'

   # MongoDB Config
   app.config['MONGODB_DB'] = 'mydatabase'
   app.config['MONGODB_HOST'] = 'localhost'
   app.config['MONGODB_PORT'] = 27017

   # Create database connection object
   db = MongoEngine(app)

   class Role(db.Document, RoleMixin):
       name = db.StringField(max_length=80, unique=True)
       description = db.StringField(max_length=255)

   class User(db.Document, UserMixin):
       email = db.StringField(max_length=255)
       password = db.StringField(max_length=255)
       active = db.BooleanField(default=True)
       confirmed_at = db.DateTimeField()
       roles = db.ListField(db.ReferenceField(Role), default=[])

   # Setup Flask-Security
   user_datastore = MongoEngineUserDatastore(db, User, Role)
   security = Security(app, user_datastore)

   # Create a user to test with
   @app.before_first_request
   def create_user():
       user_datastore.create_user(email='matt@nobien.net', password='password')

   # Views
   @app.route('/')
   @login_required
   def home():
       return render_template('index.html')

   if __name__ == '__main__':
       app.run()


Basic Peewee Application
************************


Peewee Install requirements
===========================

   $ mkvirtualenv <your-app-name>
   $ pip install flask-security flask-peewee


Peewee Application
==================

The following code sample illustrates how to get started as quickly as
possible using Peewee:

   from flask import Flask, render_template
   from flask_peewee.db import Database
   from peewee import *
   from flask_security import Security, PeeweeUserDatastore, \
       UserMixin, RoleMixin, login_required

   # Create app
   app = Flask(__name__)
   app.config['DEBUG'] = True
   app.config['SECRET_KEY'] = 'super-secret'
   app.config['DATABASE'] = {
       'name': 'example.db',
       'engine': 'peewee.SqliteDatabase',
   }

   # Create database connection object
   db = Database(app)

   class Role(db.Model, RoleMixin):
       name = CharField(unique=True)
       description = TextField(null=True)

   class User(db.Model, UserMixin):
       email = TextField()
       password = TextField()
       active = BooleanField(default=True)
       confirmed_at = DateTimeField(null=True)

   class UserRoles(db.Model):
       # Because peewee does not come with built-in many-to-many
       # relationships, we need this intermediary class to link
       # user to roles.
       user = ForeignKeyField(User, related_name='roles')
       role = ForeignKeyField(Role, related_name='users')
       name = property(lambda self: self.role.name)
       description = property(lambda self: self.role.description)

   # Setup Flask-Security
   user_datastore = PeeweeUserDatastore(db, User, Role, UserRoles)
   security = Security(app, user_datastore)

   # Create a user to test with
   @app.before_first_request
   def create_user():
       for Model in (Role, User, UserRoles):
           Model.drop_table(fail_silently=True)
           Model.create_table(fail_silently=True)
       user_datastore.create_user(email='matt@nobien.net', password='password')

   # Views
   @app.route('/')
   @login_required
   def home():
       return render_template('index.html')

   if __name__ == '__main__':
       app.run()


Mail Configuration
******************

Flask-Security integrates with Flask-Mail to handle all email
communications between user and site, so it's important to configure
Flask-Mail with your email server details so Flask-Security can talk
with Flask-Mail correctly.

The following code illustrates a basic setup, which could be added to
the basic application code in the previous section:

   # At top of file
   from flask_mail import Mail

   # After 'Create app'
   app.config['MAIL_SERVER'] = 'smtp.example.com'
   app.config['MAIL_PORT'] = 465
   app.config['MAIL_USE_SSL'] = True
   app.config['MAIL_USERNAME'] = 'username'
   app.config['MAIL_PASSWORD'] = 'password'
   mail = Mail(app)

To learn more about the various Flask-Mail settings to configure it to
work with your particular email server configuration, please see the
Flask-Mail documentation.


Proxy Configuration
*******************

The user tracking features need an additional configuration in HTTP
proxy environment. The following code illustrates a setup with a
single HTTP proxy in front of the web application:

   # At top of file
   from werkzeug.config.fixers import ProxyFix

   # After 'Create app'
   app.wsgi_app = ProxyFix(app.wsgi_app, num_proxies=1)

To learn more about the "ProxyFix" middleware, please see the Werkzeug
documentation.
