Developer Guides

Development Environment

Suggest Edits

This section illustrates how to prepare your development environment so you can run the sample integration locally. As mentioned, the sample application is developed with a React user-interface and a Python 3 backend. You are not limited to using React and/or Python, and can use any contemporary web application technology to build an EPC application.


The sample application you will build, ZipRight, has 2 components:

  1. A User-Interface (UI) application - which will be embedded in the host Encompass web application and will interact with the EPC JavaScript API

  2. A backend application - which will act as a middleware between the UI, the USPS API, and the EPC REST API


Time to prepare your development environment! 👩‍💻


User-Interface:

  1. Install Node version 12 and Node Package Manager (npm) version 6
  2. Install the Visual Studio Code IDE

Installing Node and Node Package Manager


You can download and install the latest iteration of Node version 12 from nodejs.org. This installation includes Node Package Manager version 6, a popular JavaScript dependency manager utilized by the sample application. Once installed, you can check the specific versions of Node and NPM by typing the following commands in your shells:

$ node --version

$ npm --version

Installing the Visual Studio Code IDE


You can download and install the latest version of Visual Studio Code from code.visualstudio.com. It is a lightweight and performant IDE optimized for building and debugging modern web and cloud applications in any application framework. It has extensive tooling and plugins for both JavaScript and Python development. Alternatively, you can skip this step and just use an IDE or editor of your choosing.


Backend:

  1. Install Python 3 and the Python Package Installer (pip)
  2. Sign up for an ngrok account and install its client application

Installing Python 3


You can download and install the latest version of Python 3 from python.org. Starting with Python 3.4, the Python Package Installer (pip) is included by default with the Python binary installers. The Python Package Installer is the installer program for the external Python dependencies of EPC's backend application.

Please note, your OS might be preinstalled with an older version of Python. For example, macOS is preinstalled with Python 2. To check your versions of python and pip, after installation, enter the following commands in your shells:

$ python --version

$ pip --version

If the returned version does not match Python 3, make sure the environment path points to the folder where you installed Python.


Sign up for an ngrok account and install its client application

300

ngrok is a tool that allows you to expose a web server running on your local machine to the internet. When you tell ngrok which port your web server is listening on, it will generate publicly-accessible URLs whose traffic is tunneled to the specified port on your machine. For ZipRight, you will use ngrok in two ways:

  1. To access ZipRight's UI (which will be served locally at localhost:3000) from the public internet, as it will be embedded in an Encompass application
  2. To allow ZipRight's backend (which will be served locally at localhost:8080) to receive transactional webhooks (HTTP callbacks) triggered by the EPC platform

You can download and install ngrok from this location. Follow the instructions to unzip the executable in a folder. Next, sign up for an account on the ngrok website, and connect your instance of the ngrok client to your online account by copying your ngrok auth token from your account and running this command in your shell:

$ ngrok authtoken <YOUR_AUTHTOKEN>

After connecting to your ngrok account, save the following YAML configuration file to the default location of your operating system:


YAML file contents: 

tunnels:
  user-interface:
    proto: http
    addr: 8080
  back-end:
    proto: http
    addr: 3000

File location: 

/Users/{{user_id}}/.ngrok2/ngrok.yml

/Users/{{user_id}}/.ngrok2/ngrok.yml

C:\Users\{{user_id}}\.ngrok2\ngrok.yml

Now you can run the following command in your shell to start ngrok:

ngrok start --all

You should see the following output on your shell. It displays the public URLs that ngrok generated to tunnel their traffic to your configured local ports:

ngrok by @inconshreveable                                       (Ctrl+C to quit)
                                                                                
Session Status                online                                            
Account                       EPC (Plan: Free)                      
Version                       2.3.35                                            
Region                        United States (us)                                
Web Interface                 http://127.0.0.1:4040                             
Forwarding                    http://3d5e2d38.ngrok.io -> http://localhost:8080 
Forwarding                    https://3d5e2d38.ngrok.io -> http://localhost:8080
Forwarding                    http://db0a1b1c.ngrok.io -> http://localhost:3000 
Forwarding                    https://db0a1b1c.ngrok.io -> http://localhost:3000
                                                                                
Connections                   ttl     opn     rt1     rt5     p50     p90       
                              0       0       0.00    0.00    0.00    0.00

Now that you have completed the prerequisites and prepared your development environment, you can start developing ZipRight, your first EPC application! 🎉

Updated over 4 years ago

What’s Next