.. _prepare_for_publish_and_deploy:
*************************************
Prepare App for Publishing and Deploy
*************************************
**Last Updated:** May 2020
In this tutorial you will prepare the app for publishing and deployment. The app source code will be published to `GitHub `_ under an `open source license `_. Among other things, this will allow you to track future changes to the app and it will allow others to view the code and modify it for their own use. Having the app code published on GitHub will also make it easier to download when installing the app on a production server.
The following topics are covered in this tutorial:
* Sanitizing code for public publishing
* README
* Open Source Licenses
* setup.py Metadata
* Resource Files / Package Data
.. figure:: ./resources/prepare_publish_solution.png
:width: 800px
:align: center
0. Start From Previous Solution (Optional)
==========================================
If you wish to use the previous solution as a starting point:
.. parsed-literal::
git clone https://github.com/tethysplatform/tethysapp-earth_engine.git
cd tethysapp-earth_engine
git checkout -b rest-api-solution rest-api-solution-|version|
1. Move Service Account Credentials to Settings
===============================================
Although using the :file:`gee/params.py` file to store our service account credentials is convenient, it poses a potential risk of exposing sensitive information to the public. This could occur if this file is accidentally committed and pushed to GitHub. It will also be difficult to set these settings in a production environment, because the :file:`gee/params.py` file will not be as easily accessible. To address this problem, you will create two custom app settings for storing this information in the database, instead of in a file.
1. Define two custom settings by appending the following method to the bottom of the ``EarthEngine`` class in :file:`app.py`:
.. code-block:: python
from tethys_sdk.app_settings import CustomSetting
.. code-block:: python
def custom_settings(self):
"""
Custom settings.
"""
custom_settings = (
CustomSetting(
name='service_account_email',
type=CustomSetting.TYPE_STRING,
description='Email associated with the service account.',
default='',
required=False,
),
CustomSetting(
name='private_key_file',
type=CustomSetting.TYPE_STRING,
description='Path to service account JSON file containing the private key.',
default='',
required=False,
),
)
return custom_settings
2. **Replace** the logic that authenticates the service account at the top of :file:`gee/methods.py` with the following:
.. code-block:: python
from ..app import EarthEngine as app
.. code-block:: python
service_account = app.get_custom_setting('service_account_email')
private_key_path = app.get_custom_setting('private_key_file')
if service_account and private_key_path and os.path.isfile(private_key_path):
try:
credentials = ee.ServiceAccountCredentials(service_account, private_key_path)
ee.Initialize(credentials)
log.info('Successfully initialized GEE using service account.')
except EEException as e:
log.warning('Unable to initialize GEE using service account. If installing ignore this warning.')
else:
try:
ee.Initialize()
except EEException as e:
log.warning('Unable to initialize GEE with local credentials. If installing ignore this warning.')
3. **Remove** the following import statement from the top of :file:`gee/methods.py`:
.. code-block:: python
from . import params as gee_account
4. **Delete** :file:`gee/params.py`.
2. Set Service Account Settings for the App
===========================================
1. Navigate to ``_.
2. Press the **Settings** button (button with gear icon) located on the right side of the header of the app.
3. Scroll to the **CUSTOM SETTINGS** section of the settings page.
4. Enter the client email and the path to the key file as before in the ``service_account_email`` and ``private_key_file`` fields, respectively.
5. Scroll to the bottom of the page and press the **Save** button.
6. Use the **Apps** link to navigate back to the apps library and launch the app.
7. Navigate to the Viewer page and verify that all of the viewer functionality is working: load dataset imagery, plot area of interest, and clipping by boundary.
3. Add a README
===============
In this step you will create a README file with instructions for installing and using the app. GitHub support the `Markdown syntax `_, so that will be used to add more structure to the README.
Create a new file called :file:`README.md` in the same directory as the :file:`setup.py` with the following contents:
.. code-block:: md
# Earth Engine App
The Earth Engine is a Tethys App that demonstrates how to use Google Earth Engine to visualize remotely sensed datasets.
## Installation
Install the app with the Tethys Platform environment activated as follows:
```
# For development installations
tethys install -d
# For production installations
tethys install
```
## Settings
The app has two Custom Settings that can be used to configure the app to use a [Google Earth Engine service account](https://developers.google.com/earth-engine/service_account):
* **service_account_email**: Email associated with the service account.
* **private_key_file**: Path to service account JSON file containing the private key.
## Authenticate for Development
Alternatively, you can authenticate with your personal Google Earth Engine account by running the following command:
```
earthengine authenticate
```
**WARNING**: Do not use personal Google Earth Engine credentials for a production installation.
4. Add a License File
=====================
In this step you will add an appropriate open source license to your project. This will allow others to legally reuse and modify your code. It provides a disclaimer that absovles you from any responsibility should your code not function properly.
1. Navigate to ``_ and peruse the list of Popular License.
2. Click on the link for the `BSD 3-Clause "New" or "Revised" license `_ or a license of your choice.
3. Create a new file called :file:`LICENSE` in the same directory as the :file:`setup.py`.
4. Copy the license text into the :file:`LICENSE` file.
5. Replace any values in angle brackets (e.g. ) with appropriate values.
5. Add Metadata to Setup.py
===========================
In this step you will add appropriate metadata to the :file:`setup.py`. This metadata will be used by packaging services such as the Python Package Index (PyPI) or Conda, should you choose to distribute your package on one of those platforms. It is also used by ``pip`` when a user lists information about an installed package. An explanation of possible ``setup`` keywords you can use can be found here: `New and Changed setup() Keywords `_. As a minimum, you should set the version
1. Open :file:`setup.py`, located in the root directory of your app code.
2. Replace the ``setup`` function call with the following, replacing values in angle brackets with your information:
.. code-block:: python
:emphasize-lines: 1-2,6-10,12
with open('README.md', 'r') as f:
long_description = f.read()
setup(
name=release_package,
version='1.0.0',
description='A Google Earth Engine demonstration Tethys App.',
long_description=long_description,
author='',
author_email='',
url='', # The URL will be set in a future step.
license='BSD 3-Clause',
packages=find_namespace_packages(),
package_data={'': resource_files},
include_package_data=True,
zip_safe=False,
install_requires=dependencies,
)
.. note::
We recommend using semantic versioning for your projects. See: `Introduction to Semantic Versioning `_ and `Semantic Versioning 2.0.0 `_.
.. tip::
Using contents of the :file:`README.md` as the ``long_description`` as demonstrated above is a best practice.
6. Verify Setup.py
==================
In this step, you will reinstall the app to verify that the :file:`setup.py` is free of errors.
1. Change into the directory containing your :file:`setup.py` and :file:`install.yml` and run the install command:
.. code-block:: bash
tethys install -d
2. Run the following command to list metadata about the app:
.. code-block:: bash
pip show tethysapp-earth_engine
Which should yield:
.. code-block::
Name: tethysapp-earth-engine
Version: 1.0.0
Summary: A Google Earth Engine demonstration Tethys App.
Home-page: UNKNOWN
Author:
Author-email:
License: BSD 3-Clause
Location:
Requires:
Required-by:
7. Copy Resource Files
======================
Up to this point, the app has been installed in development mode (``tethys install -d``). This means that the code that you have been working on has been **linked** to the Python :file:`site-packages` directory so that the changes you make are immediately available to Python without needing to reinstall.
In a production environment you will want to install the app normally (``tethys install``). When a Python package is installed, the files are **copied** to the Python :file:`site-packages` directory. By default, only Python files (with the ``py`` extension) are copied to the :file:`site-packages` directory. Other types of files needed by a a Python package are referred to as "package data" or "resource files".
Resource files that are required by in Tethys Apps include CSS, JavaScript, HTML, and images. Open :file:`setup.py` and inspect lines 12-13:
.. code-block::
resource_files = find_resource_files('tethysapp/' + app_package + '/templates', 'tethysapp/' + app_package)
resource_files += find_resource_files('tethysapp/' + app_package + '/public', 'tethysapp/' + app_package)
These lines use a helper function provided by Tethys Platform ``find_resource_files`` to automatically locate and include files in the :file:`templates` and :file:`public` directories. If your app had additional directories with non-python files that need to be included, you would need to add an additional call to ``find_resource_files`` like so:
.. code-block::
resource_files += find_resource_files('tethysapp/' + app_package + '', 'tethysapp/' + app_package)
There are no additional resource files for the Earth Engine app, so no additional calls to ``find_resource_files`` are required.
8. Solution
===========
This concludes this portion of the GEE Tutorial. You can view the solution on GitHub at ``_ or clone it as follows:
.. parsed-literal::
git clone https://github.com/tethysplatform/tethysapp-earth_engine.git
cd tethysapp-earth_engine
git checkout -b prepare-publish-solution prepare-publish-solution-|version|