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.
Make sure you've installed the base requirements:
- virtualenvwrapper (optional)
- PostgreSQL (optional?)
While virtualenvwrapper is optional, these docs assume it's installed. If you skip it you may need to modify some commands accordingly.
The Rattail database layer only supports PostgreSQL as its backend; however it needn't be installed locally if there's already one on the network etc. Also your needs may not require the database layer at all, but in practice they likely would, e.g. it's required by the web app.
Create the Virtual Environment
First step is simple enough:
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.)
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',)