Add NewProject

NewProject.md

@@ -0,0 +1,140 @@
+# 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](LilSnippets-ProjectNaming.-).
+
+## Prerequisites
+
+Make sure you've installed the base requirements:
+
+ * Python
+ * pip
+ * virtualenv
+ * virtualenvwrapper (optional)
+ * PostgreSQL (optional?)
+
+**NOTE:** *While virtualenvwrapper is optional, these docs assume it's installed.  If you skip it you may need to modify some commands accordingly.*
+
+**NOTE:** *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:
+
+```sh
+mkvirtualenv poser
+```
+
+Then with your new environment activated, install the Tailbone package:
+
+```sh
+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:
+
+```sh
+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):
+
+```sh
+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:
+
+```sh
+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.:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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 [[https://pypi.python.org/pypi/alembic|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:
+
+```sh
+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.:
+
+```python
+down_revision = None
+branch_labels = ('poser',)
+```