Creating a new Project

This page describes the process of both creating a new Rattail-based project, as well as setting up its development environment.

Note that the examples below use 'poser' as the name of the new project. Please replace that with whatever you like, in practice.

See also How to Name Your Project.

Prerequisites

Make sure you've installed the base requirements:

• Python
• pip
• virtualenv
• virtualenvwrapper (optional)
• PostgreSQL (optional?)

Create the Virtual Environment

First step is simple enough:

mkvirtualenv poser

Then with your new environment activated, install the Tailbone package:

pip install Tailbone

Create the Project

Now with your environment still activated, cd to wherever you like (e.g. ~/src) and create a new project skeleton like so:

mkdir -p ~/src
cd ~/src
pcreate -s rattail poser

This will have created a new project at ~/src/poser which you can then edit as you wish. At some point you will need to "install" this project to the environment like so (again with environment active):

cd ~/src/poser
pip install -e .

Setup the App Environment

Any project based on Rattail will effectively be its own "app" (usually), but Rattail itself provides some app functionality as well. However all such apps require config files, usually. If running a web app then you may also need to have configured a folder for session storage, etc. To hopefully simplify all this, there are a couple of commands you should now run, with your virtual environment still active:

rattail make-appdir
cdvirtualenv app
rattail make-config -T rattail
rattail make-config -T quiet
rattail make-config -T web

This will have created a new 'app' folder in your environment (e.g. at /srv/envs/poser/app) and then created rattail.conf and web.conf files within that app dir. Note that there will be other folders inside the app dir as well; these are referenced by the config files.

But you're not done yet... You should likely edit the config files, at the very least edit rattail.conf and change the default.url value (under [rattail.db] section) which defines the Rattail database connection.

Create the Database

If applicable, it's time for that. First you must literally create the user and database on your PostgreSQL server, e.g.:

sudo -u postgres createuser --no-createdb --no-createrole --no-superuser poser
sudo -u postgres psql -c "alter user poser password 'mypassword'"
sudo -u postgres createdb --owner poser poser

Then you can install the schema; with your virtual environment activated:

cdvirtualenv
alembic -c app/rattail.conf upgrade heads

At this point your 'poser' database should have some empty tables. To confirm, on your PG server do:

sudo -u postgres psql -c '\d' poser

Create Admin User

If your intention is to have a web app, or at least to test one, you'll probably want to create the initial admin user. With your env active:

cdvirtualenv
rattail -c app/quiet.conf make-user --admin myusername

This should prompt you for a password, then create a single user and assign it to the Administrator role.

Install Sample Data

If desired, you can install a bit of sample data to your fresh Rattail database. With your env active do:

cdvirtualenv
rattail -c app/quiet.conf -P import-sample

Run Dev Web Server

With all the above in place, you may now run the web server in dev mode:

cdvirtualenv
pserve --reload app/web.conf

And finally..you may browse your new project dev site at http://localhost:9080/ (unless you changed the port etc.)

Schema Migrations

Often a new project will require custom schema additions to track/manage data unique to the project. Rattail uses Alembic for handling schema migrations. General usage of that is documented elsewhere, but a little should be said here regarding new projects.

The new project template includes most of an Alembic "repo" for schema migrations. However there is one step required to really bootstrap it, i.e. to the point where normal Alembic usage will work: you must create the initial version script. Before you do this, you should be reasonably happy with any ORM classes you've defined, as the initial version script will be used to create that schema. Once you're ready for the script, this command should do it:

cdvirtualenv
bin/alembic -c app/rattail.conf revision --autogenerate --version-path ~/src/poser/poser/db/alembic/versions/ -m 'initial Poser tables'

You should of course look over and edit the generated script as needed. In particular you should add a branch label and clear out the "down" revision, e.g.:

down_revision = None
branch_labels = ('poser',)