New Tethys App Project

Last Updated: June 2017

Tethys Platform provides an easy way to create new app projects called a scaffold. The scaffold generates a Tethys app project with the minimum files and the folder structure that is required (see App Project Structure).

Tip

You will need to use the command line/terminal to manage your app and run the development server. See the Terminal Quick Guide article for some tips if you are new to command line.

1. Generate Scaffold

To generate a new app using the scaffold, open a terminal, press CTRL-C to stop the development server if it is still running, and execute the following commands:

Linux and Mac:

         $ t
(tethys) $ mkdir ~/tethysdev
(tethys) $ cd ~/tethysdev
(tethys) $ tethys scaffold dam_inventory

Windows:

Locate the tethys_cmd.bat (in the TETHYS_HOME directory) and double-click it to open a new command windows with the Tethys environment activated. Then run the following commands:

(tethys) $ mkdir C:%HOMEPATH%\tethysdev
(tethys) $ cd %HOMEPATH%\tethysdev
(tethys) $ tethys scaffold dam_inventory

Tip

Windows Users: If you have admin rights on your computer, it is even better to right-click on the tethys_cmd.bat and select Run as Administrator.

You will be prompted to enter metadata about your app such as, proper name, version, author, and description. All of these metadata are optional. You can accept the default value by pressing enter, repeatedly.

In a file browser change into your Home directory and open the tethysdev directory. If the scaffolding worked, you should see a directory called tethysapp-dam_inventory. All of the source code for your app is located in this directory. For more information about the app project structure, see App Project Structure.

2. Development Installation

Now that you have a new Tethys app project, you need to install the app on your development Tethys Portal. In a terminal, change into the tethysapp-dam_inventory directory and execute the python setup.py develop command. Be sure to activate the Tethys Python conda environment if it is not already activated (see line 1 of the first code block):

Linux and Mac:

(tethys) $ cd ~/tethysdev/tethysapp-dam_inventory
(tethys) $ python setup.py develop

Windows:

(tethys) $ cd C:%HOMEPATH%\tethysdev\tethysapp-dam_inventory
(tethys) $ python setup.py develop

Tip

Windows Users: If you get an error when running python setup.py develop, then you have insufficient permissions to install your app in development mode. Either try opening the tethys_cmd.bat as an administrator and run the commands again, or run python setup.py install. The disadvantage to this method is that each time you want Tethys to reflect changes to your app code, you will need to run python setup.py install again.

3. View Your New App

Use start up the development server:

(tethys) $ tethys manage start

OR use the tms alias:

(tethys) $ tms

Note

If you get errors related to Tethys not being able to connect to the database, start the database by running:

(tethys) $ tstartdb

You can also stop the Tethys database by running:

(tethys) $tstopdb

Browse to http://127.0.0.1:8000/apps in a web browser. If all has gone well, you should see your app listed on the app library page. Exploring your new app won't take long, because there is only one page. Familiarize yourself with different parts of the app interface (see below).

../../_images/app_controls.png

Parts of a Tethys app interface: (1) app navigation toggle and app branding; (2) exit button, settings, button, and custom buttons; (3) app navigation, (4) app content, and (5) app actions.

Tip

To stop the development server press CTRL-C.

4. App Project Paths

Throughout the tutorial, you will be asked to open various files. Most of the files will be located in your app package directory which shares the name of your app: "dam_inventory". If you generated your scaffold exactly as above, this directory will be located at the following path:

# Linux and Mac
~/tethysdev/tethysapp-dam_inventory/tethysapp/dam_inventory/

# Windows
C:%HOMEPATH%\tethysdev\tethysapp-dam_inventory\tethys_app\dam_inventory\

For convenience, all paths in the following tutorials will be given relative to the app package directory. For example:

# This path:
~/tethysdev/tethysapp-dam_inventory/tethysapp/dam_inventory/controllers.py

# Will be referred to as:
controllers.py

Tip

As you explore the contents of your app project, you will notice that many of the directories have files named __init__.py. Though many of these files are empty, they are important and should not be deleted. They inform Python that the containing directory is a Python package. Python packages and their contents can be imported in Python scripts. Removing the __init__.py files will result in breaking import statements and it could make some of your code inaccessible. Similarly, if you add a directory to your project that contains Python modules and you would like them to be made available to your code, add a __init__.py file to the directory to make it a package.