Development Installation

Last Updated: July 13, 2016

IMPORTANT:

Tethys Platform is built on the Python web framework Django. If you are not familiar with Django development, it is required that you read and complete all of the tutorials in the First Steps section of the Django Documentation before embarking on Tethys Platform development.

1. Install the Dependencies

Complete steps 1-2 from the normal installation instructions.

2. Create Project Directory

Create a project directory for the Tethys source code in a convenient location. This will be the directory you will work out of. For this tutorial, the directory will be called tethysdev and it will be located in the home directory. Also, create a directory inside your project directory called apps for any Tethys app projects you work on during development of Tethys.

$ mkdir ~/tethysdev
$ cd ~/tethysdev
$ mkdir apps

3. Pull the Source Code

Tethys Platform is versioned with Git and hosted on GitHub. Change into the project directory you created in the previous step and execute the following commands to download the source code:

$ git clone https://github.com/tethysplatform/tethys.git
$ git clone https://github.com/tethysplatform/tethys_dataset_services.git
$ git clone https://github.com/tethysplatform/tethys_docker.git

When you are done, your project directory should have the following contents:

tethysdev/
  |-- apps/
  |-- tethys/
  |-- tethys_dataset_services/
  |-- tethys_docker/

A brief explanation of each directory is provided below. For more details about the organization of Tethys Platform source code, see :doc:`../overview`.

• apps: a directory to that will contain Tethys app projects used for development purposes.
• tethys: The main Django site project for Tethys. Most of the source for tethys platform is contained in this project.
• tethys_dataset_services: A Python module providing an interface with CKAN, HydroShare, and GeoServer that was made a separate Python module to allow it's use by web services external to Tethys Platform installations.
• tethys_docker: The Dockerfiles that can be used to create the Tethys Docker images.

It is likely that you will be working in a branch other than the master branch. To switch branches change into the source directory and use the git checkout <branch> command. For example:

$ cd tethys
$ git checkout dev

4. Create Virtual Environment and Install Tethys Platform

Many of the Tethys command line utilities depend on Tethys being installed in a default location: /usr/lib/tethys/src for unix environments. This location is not ideal for development, so instead you will create a symbolic link from where you downloaded the source to the default location. The virtual environment will also be installed in the default location.

1. If you have an existing installation of Tethys in /usr/lib/tethys, you should delete it:

   $ sudo rm -rf /usr/lib/tethys
   

2. Create a Python virtual environment and activate it:

   $ sudo mkdir -p /usr/lib/tethys
   $ sudo chown `whoami` /usr/lib/tethys
   $ virtualenv --no-site-packages /usr/lib/tethys
   $ . /usr/lib/tethys/bin/activate
   

3. Create a symbolic link from the tethys source code you downloaded to the default location:

   $ ln -s ~/tethysdev/tethys /usr/lib/tethys/src
   

4. Install each of the projects that you downloaded in development mode. Development mode any changes you make to the source code to take effect immediately without requiring you to reinstall the project:

   $ cd ~/tethysdev/tethys_dataset_services && python setup.py develop
   

5. Install the Python modules that Tethys requires:

   $ pip install -r /usr/lib/tethys/src/requirements.txt
   $ python /usr/lib/tethys/src/setup.py develop
   

6. Restart the Python virtual environment:

   $ deactivate
   $ . /usr/lib/tethys/bin/activate
   

5. Install Tethys Software Suite Using Docker

1. Initialize the Tethys Software Suite Docker containers with the default parameters:

   $ tethys docker init -d
   

   Here are the default passwords that you will need to know to finish setup:

   PostGIS Database User Passwords:

   • tethys_default: pass
   • tethys_db_manager: pass
   • tethys_super: pass

   Geoserver Username and Password:

   • admin: geoserver

   52 North WPS Username and Password:

   • wps: wps

2. Start the Docker containers:

   $ tethys docker start
   

   NOTE:

   Although each Docker container appears to start instantaneously, it may take several minutes for the started containers to be fully up and running.

   TIP:

   You can start and stop individual containers using the container option:

   # Start one container
   $ tethys docker start --container postgis
   
   # Start two containers
   $ tethys docker start -c postgis geoserver
   

6. Finish Installation as Normal

Finish the installation by following steps 6-9 of the normal installation instructions.