.. program:: mangage_defernia.py Getting started =============== If Defernia has :doc:`installed `, there might be :program:`manage_defernia.py` command. It helps you to make a configuration, initialize a database, or run a web server. .. seealso:: Script :doc:`manage_defernia.py ` Configuration file ------------------ Defernia is a system that supports multiple instances, and instances' metadata are stored in the configuration file. From here, we assume that our configuration filename is :file:`instance.cfg`. (Of course, there's no such file currently.) You can name it freely like :file:`dev.cfg` or :file:`prod.cfg`. You can pass a filename that doesn't exist into :option:`--config ` option, and the script will confirm would you want to create a such configuration file. .. sourcecode:: console $ manage_defernia.py shell --config instance.cfg instance.cfg doesn't exist yet; would you create it? [y] There's some fields to be set like database URL: **Repository directory path** (:data:`REPODIR_PATH`) The directory that would contain Mercurial_ repositories. By default it is a directory named :file:`repos` located in the current directory. .. sourcecode:: text Repository directory path [/home/dahlia/defernia-env/defernia/repos]: .. _Mercurial: http://mercurial.selenic.com/ **Database URL** (:data:`DATABASE_URL`) The database to be used. By default it uses SQLite with a database file (:file:`db.sqlite`) located in the current directory. .. sourcecode:: text Database URL [sqlite:////home/dahlia/defernia-env/db.sqlite]: .. seealso:: SQLAlchemy --- `Database Urls `_ **Secret key for secure session** (:data:`SECRET_KEY`) The HMAC secret key. The default key is randomly generated, so skip this if you don't know about HMAC or secure session. .. sourcecode:: text Secret key for secure cookies [ab03199d87db101aa07fd18e3dc2599a]: .. seealso:: Flask --- :ref:`sessions` Flask provdes client-side secure sessions. Context Local :class:`flask.session` The session object works pretty much like an ordinary dict, with the difference that it keeps track on modifications. :rfc:`2104` --- HMAC: Keyed-Hashing for Message Authentication This document describes HMAC, a mechanism for message authentication using cryptographic hash functions. HMAC can be used with any iterative cryptographic hash function, e.g., MD5, SHA-1, in combination with a secret shared key. The cryptographic strength of HMAC depends on the properties of the underlying hash function. **Facebook App ID**, **Facebook App key**, **Facebook App secret key** Keys of Facebook_ application used for login. You can create a new Facebook application from `Facebook Developers`_ home. .. sourcecode:: text Facebook App ID: 123456789012345 Facebook App key: 6753a27847d7e4e3518b1837c2f0e716 Facebook App secret key: edd661737bf101806acb51d83e65c5c1 .. seealso:: Facebook Developers --- `Create Application`_ .. _Facebook: http://www.facebook.com/ .. _Facebook Developers: http://developers.facebook.com/ .. _Create Application: https://www.facebook.com/developers/createapp.php **Twitter App key**, **Twitter App secret key** Key pair of Twitter_ application used for login. You can create a new Twitter application from `Twitter Developers`_ home. .. sourcecode:: text Twitter App key: X0DS1WP71Mhs8NN0r7paRg Twitter App secret key: AuJyVWiQm9Jvm61koDP0mv3Gsjgf6GDRrNsvqm5qL .. seealso:: Twitter Developers --- `Register an Application`_ Create your own Twitter app. Tiwtter Developers --- `Authenticating Requests with OAuth`_ Twitter uses the open authentication standard OAuth for authentication. .. _Twitter: http://twitter.com/ .. _Twitter Developers: http://dev.twitter.com/ .. _Register an Application: https://dev.twitter.com/apps/new .. _Authenticating Requests with OAuth: https://dev.twitter.com/pages/auth .. seealso:: Flask --- :ref:`config` Database initialization ----------------------- What you have to do next is creating tables into your relational database. There are to recommended relational databases: SQLite_ 3+ SQLite is a small and powerful file-based relational database. It is recommended for development-purpose. PostgreSQL_ 8.3+ PostgreSQL is a powerful object-relational database system. We recommend it for production-use. You make a decision, and then, initialize the database via :program:`manage_defernia.py initdb` command: .. sourcecode:: console $ manage_defernia.py initdb --config instance.cfg No news is good news. It doesn't print anything unless errors happen. .. note:: If you would use SQLite_, the data file will be automatically created. But if you would use PostgreSQL_, the database to be used have to be created first. Create a database via the :program:`createdb` command PostgreSQL provides: .. sourcecode:: console $ createdb -U postgres -E utf8 -T postgres defernia_db .. seealso:: Command :ref:`manage_defernia.py initdb ` .. _SQLite: http://www.sqlite.org/ .. _PostgreSQL: http://www.postgresql.org/ Running unit tests ------------------ To check whether the installation has sucessful, we can run the unit tests. :program:`setup.py test` command runs the unit tests. .. sourcecode:: console $ python setup.py test running test [100%] 2 of 2 Time: 0:00:00 Failures: 0/2 (6 assertions) .. _web-server: Web server ---------- We finished configuring an instance. Now we can run the development web server from command line: .. sourcecode:: console $ manage_defernia.py runserver --config instance.cfg .. seealso:: Command :ref:`manage_defernia.py runserver ` How to serve on WSGI servers ---------------------------- .. note:: It explains advanced details. If you don't know about WSGI, skip this section and follow :ref:`web-server` section. Defernia web application is WSGI-compliant, so it can be served on WSGI servers. For example, in order to serve it on Meinheld_ server, make a script:: import defernia.web import meinheld.server app = defernia.web.create_app(config_filename='instance.cfg') meinheld.server.listen(('0.0.0.0', 8080)) meinheld.server.run(app) Let's cut to the chase. :func:`defernia.web.create_app()` makes a WSGI application and returns it. It takes a ``config_filename`` optionally (and it have to be passed by keyword, not positional). And then, pass the created WSGI application into your favorite WSGI server. .. _Meinheld: http://meinheld.org/