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 'myrattail' as the name of the new project. Please replace that with whatever you like, in practice.


Make sure you've installed the base requirements:

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:

mkvirtualenv myrattail

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 myrattail

This will have created a new project at ~/src/myrattail 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/myrattail
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/myrattail/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 myrattail
sudo -u postgres psql -c "alter user myrattail password 'mypassword'"
sudo -u postgres createdb --owner myrattail myrattail

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

alembic -c app/rattail.conf upgrade heads

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

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

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:

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:

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:

pserve --reload app/web.conf

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

NewProject (last edited 2016-12-07 19:28:49 by LanceEdgar)