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.
First step is simple enough:
Then with your new environment activated, install the Tailbone package:
pip install Tailbone
Now with your environment still activated,
cd to wherever you like
~/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 .
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
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.
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
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.
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
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.)
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',)