A case and task tracker

##Installation and Management

Create a conda environment to run the app:

conda create -n octopus -f requirements/prod.txt

Activate it and use pip to install the balance of the requirements:

activate octopus
pip install -r requirements.txt

To start the app, run from the root octopus folder:

python manage.py server

###Deployment

In your production environment, make sure the OCTOPUS_ENV environment variable is set to "prod".

Twisted is the production server of choice, so conda install gevent is needed before releasing to production.

To light up the production server, run python run_prod.py. The server will light up on localhost:9001

###Shell

To open the interactive shell, run:

python manage.py shell

THe shell has access to all database models.

##App Structure

###Forms and Views Octopus uses routes to organize the page views, and blueprints to organize those routes. The app is organized as follows:

• Public
• User
• Case
• Task
• Project

Each of those sections is contained in its own folder, the contents of which are essentially clones. All route folders contain:

• init file (empty, but required by flask)
• forms.py
• views.py

Some folders contain utils.py and queries.py--these files contain route-specific tools for loading pages or accessing data.

Views.py contains the definition for each page that falls under the route, as well as nav bar contents that belong to that section. Each page must contain a route definition and a template to be rendered. It may also contain optional decorators, variables defined for that page, code to be executed, or a form (imported from forms.py).

Forms.py contains a function for every unique form with in a route. For example, octopus/case/forms.py contains NewCaseForm, EditCoreCaseForm, etc. These forms are called by a function within views.py.

###Models All models on which the database is constructed are consolidated into one file in the main octopus directory called models.py. This is the file on which database migrates are based. Further explanation of how the models are structured follows in the Database section.

###Templates and Static Files Templates (octopus/templates) are also divided into sections based on the main view partitioning of the app. There is a separate template file for every page which is accessible under a route (e.g. octopus/templates/case/all_cases.html).

All templates for the app are sub-content for a single main template, octopus/template/layout.html, which makes the app look consistent and precludes the annoying replication of headers, etc. Should you need to add an additional error handling page, the templates are here as well (rendering occurs in app.py).

Macros for datatables, datepickers, rendering links, etc, are in octopus/templates/macros. Markdown support is in octopus/templates/markdown.

Static files (octopus/static) are partitioned in their own area and can be accessed by the entire app. This is the location for font libraries, css, javascript, and image files.

##Migrations At the moment (during development) the database is in version control. The plan is to move the database outside the repo, which will require you to save a copy of the database as backup before your migration. Make your backup before attempting an upgrade!

The migration system we are using is Alembic. Alembic provides support for several types of databases, but is probably best known for SQLite support. After making changes to the octopus/models.py file that should be reflected in the database, run the following command:

python manage.py db migrate

Alembic will run a diff on the old model and the new to detect the changes and generate a script that, when run, will tell SQLite what changes to make.

SQLite does not support deleting or renaming columns or modifying foreign keys. To circumvent these restrictions, Alembic has introduced a feature called Batch Processing. The concept behind this feature is to copy the existing data to a temporary table, drop the existing table and remake it under the new specifications, and move the data back to its proper place.

As with many new features, however, Batch Processing comes with quite a few bugs. The script generated by the migrate command often has significant errors that must be corrected by hand before update can be run. I have found the following problems so far (there may be others I haven't discovered yet):

###Indices: Batch processing does not support indices. In SQLite indices and tables are separate objects, and must be created and managed separately. In the case of batch processing a table which has an index (all of the current tables do), first drop the index:

op.drop_index(op.f('ix_cases_crd_number'), table_name='cases')

Then run batch on the table 'cases', and remake the index:

op.create_index(op.f('ix_cases_case_name'), 'cases', ['case_name'],
                unique=False)

###Create Foreign Key: If you are adding a foreign key under a batch process, the migrate script will follow the following schema for create_foreign_key:

create_foreign_key(self, name, source, referent, local_cols,
                       remote_cols, onupdate=None, ondelete=None,
                       deferrable=None, initially=None, match=None,
                       source_schema=None, referent_schema=None,
                       **dialect_kw):

However, batch process has its own create_foreign_key function, with a different schema (but the same name, which is very confusing):

create_foreign_key(
        self, name, referent, local_cols, remote_cols, **kw):

You will need to delete the extra "source" argument or you will receive a runtime error.

###SQLite sequence The alembic scripts have references to a tables it calls 'sqlite_sequence.' This reserve table is broken, so just comment them out. Otherwise the upgrade will crash.

Once you have modified your migrate script and saved your backup copy of the db, you can run:

python manage.py db upgrade