Creating a New Project¶

This describes the process of creating a new app project based on Rattail/Tailbone. It assumes you are working from a supported Development Environment.

Per convention, this doc uses “Poser” (and poser) to represent the custom app. Please adjust commands etc. accordingly. See also App Organization & Structure.

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 few 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. One change in particular you should make is to add a branch label, e.g.:

branch_labels = ('poser',)