Development Environment
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:
-
A User-Interface (UI) application - which will be embedded in the host Encompass web application and will interact with the EPC JavaScript API
-
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:
- Install
Node
version 12 and Node Package Manager (npm
) version 6 - 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:
- Install
Python 3
and the Python Package Installer (pip
) - 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
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:
- 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 - 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 about 4 years ago