Building a server-side app - Part 5: Deploy the app
In the previous tutorial, you updated the web app to access framework APIs. In this tutorial, you'll deploy the web app on a server and install the basic framework app in Zendesk Support.
The tutorial covers the following tasks:
This tutorial is the fifth part of a series on building a server-side Zendesk app:
- Part 1: Core concepts
- Part 2: Display server-side content in a Zendesk app
- Part 3: Access external APIs
- Part 4: Access framework APIs
- Part 5: Deploy the app - YOU ARE HERE
- Bonus part: Secure the app
Disclaimer: Zendesk provides this article for instructional purposes only. The Zendesk Support team does not provide support for the content. Please post any issue in the Zendesk Apps framework (ZAF) community, or search for a solution online.
If you don't have access to a web server at work, you can use a PaaS (platform as a service) option like Heroku. Depending on the service, you can deploy it for free. The tutorial's web app doesn't require a lot of server resources because it's only used occasionally by agents or admins, not the general public.
In this tutorial, you'll deploy the web app on Heroku, which has a free plan tailored for learning apps such as this one.
You can use Git, the popular version control system, to push the app files to the Heroku server.
Note: If you already have Git, update it to the latest version.
Download and run one of the following installers:
Tip: If you're a Mac user and have Homebrew installed, you can install git with
$ brew install git.
If you don't already have an Heroku account, you can sign up for a free account.
Note: If you already have a Heroku account and have the Heroku CLI, then log in to Heroku on the command line and run
$ heroku create technote-app and skip this section. (Modify the app name to make it unique.) See Creating Apps from the CLI in the Heroku docs.
Go to https://signup.heroku.com/dc, then enter your name and email, pick Python as your primary development language, then click Create Free Account.
Check your email to confirm your account. When prompted, set up a password.
After setting up a password, you'll be taken to a welcome page. Click the link to proceed.
Click the Create New App button.
Specify a name for your app, all in lowercase with no spaces or underscores. Example: "technote-app".
Note that somebody else has probably already taken that name. Modify it slightly or use a completely different one.
Click Create App.
You should be taken to the Deploy tab of your new app.
Under Deployment Method, make sure the Heroku Git option is selected, then click the link to download and install the Heroku CLI (command-line interface).
Follow the instructions to install the CLI and to log in at the command line for the first time.
Make sure you installed Git before proceeding. See Install Git above for instructions.
In your command-line interface, navigate to the folder that contains the files of your Bottle app.
If you followed the tutorial, it should be something like
Run the following command:
$ git init
This creates a local Git repository. You'll connect it to a remote repository on Heroku in the next step.
Make sure you're logged in to Heroku (
$ heroku login), then run the following command:
$ heroku git:remote -a technote-app
Important: Change "technote-app" to whatever you named your app on Heroku.
When deploying, the following configuration files need to be included in the web app's root directory:
In a text editor, create a file named Procfile and make sure it contains the following line:
web: python app.py
A Procfile lists the app's process types and the commands to start each process. The Bottle app runs a single web process, which is started by executing the
Create a file named runtime.txt and make sure it contains the following line, adjusted for your version number:
The runtime.txt file tells Heroku what Python version to use for your app. The setting ensures Heroku runs your app in the same runtime environment you used locally to develop and test the app.
To find out the version you're using locally, run the following command at the command line:
$ python3 --version
Create a file named requirements.txt and make sure it lists the following libraries:
The file lists all the external libraries the app needs to run. Update the version number of each library, if necessary. To find out the version, run the following commands:
$ pip show bottle
$ pip show requests
The content of your app_remote folder should look like this:
Your app is currently set up to run locally the following
run(host='localhost', port=8080, debug=True)
You must use different values to run the app on Heroku.
You can modify the web app as follows to work in both the local and remote environments.
In app.py, replace the last line (
run(host='localhost', port=8080, debug=True)) with the following conditional block:
if os.environ.get('APP_LOCATION') == 'heroku':
run(host="0.0.0.0", port=int(os.environ.get("PORT", 5000)))
run(host='localhost', port=8080, debug=True)
The block has two possible run statements: one for the Heroku environment and one for your local environment. At runtime, the app checks for the APP_LOCATION environment variable to decide which one to run.
Because the block introduces the 'os' library to check for the environment variable and to set the
portvalue, import the library at the top of the file:
from bottle import route, ...
In this step, you'll deploy the tutorial app to Heroku for the first time.
Add and commit all the app files to your local git repository:
$ git add .
$ git commit -a -m "Initial commit"
If not already done, login to Heroku and enter your Heroku email and password when prompted:
$ heroku login
Deploy the app:
$ git push heroku master
The command uploads the app files to the remote git repository on Heroku. Heroku then builds and deploys the app.
Note the URL of the app. You'll need to add it to the manifest file in the framework app that you'll install in Zendesk Support. Look for the following line in the push results:
remote: https://technote-app.herokuapp.com/ deployed to Heroku
The URL here is
Set the following APP_LOCATION environment variable in Heroku:
$ heroku config:set APP_LOCATION=heroku
In "Modify the run command" above, you made the app check for an environment variable named APP_LOCATION with a value of 'heroku'. It tells the app to run with the correct
You can test that the web app works by requesting the sidebar content in a browser:
The List button should appear stretched across the width of the browser window. Clicking it should list the tasks in the Asana project.
If something goes wrong, go back to your command-line interface and enter
heroku logs --tail. Check the entries for clues of possible issues.
One advantage of server-side Zendesk apps is that you can push updates once to the server to update the app in all instances of Zendesk Support. You don't need to reinstall or update the app in Zendesk Support.
In your command-line interface, navigate to your app folder.
Commit all the changes in Git:
git commit -a -m "Various updates"
If not already done, log in to Heroku and enter your Heroku email and password when prompted:
Push the files:
git push heroku master
Open and test the app in a browser.
In a text editor, open the manifest.json file and enter the new remote address of the start page:
Important: Make sure the URL matches your own app's URL on Heroku.
In a new command-line window, navigate to the app_local folder and run the following command to validate your files:
$ zcli apps:validate
Fix any problems reported by the tool, then run
Package your files for upload with the following command:
$ zcli apps:package
Sign in as an admin in Admin Center, go to Apps and integrations > Apps > Zendesk Support apps, then follow the instructions to upload and install a private app. For details, see Uploading and installing your private app in Zendesk Support.
Open the ticket interface and test the app.
In this tutorial, you deployed the web app on a server and installed the basic framework app in Zendesk Support. You can keep tweaking and making enhancements to the app if you like. For example, you could add a page that lets agents add tech note ideas to the Asana project.
You can also enhance the tutorial app to make it more secure. Click to go to the bonus tutorial now: Bonus part: Secure the app.
If you build a server-side app that other support organizations might find useful, consider making it publicly available in the Zendesk Marketplace. See the Publish your app.