The software engineering practices of continuous integration and continuous delivery are becoming mainstream for all dev teams. Thanks to tools like Travis-CI, CircleCI, Drone, and Jenkins, small teams can automate their code testing and deployment to rapidly and safely update their product every day.
Developers want to be able to commit their code to a platform like GitHub, peer-review, and have it automatically tested, built, and deployed. How can you get this working with your Functions?
After taking a look at the Functions quickstart tutorial, you might assume that the only way to deploy this code is by copying and pasting it from your local text editor to the online portal editor and pressing the restart button.
If your code is going into production for millions of users, wouldn't that kind of deploy process give you sweaty palms? Let's avoid doing that. We want to get our Functions deploys on the same level as all of our other systems, by using the industry standard testing and CI/CD tools.
We can get this process working very quickly using the Functions CLI tool.
## Globally install the Command Line tool ## Make sure you have Node.js installed first npm install pubnub-cli -g
Functions CLI
The Functions CLI gives you the ability to:
- Init – Download the remote Function and event handlers locally
- Log – Log the event handler output to console
- Login – Authorize with PubNub and write session to disk
- Logout – Remove local session from disk
- Pull – Download remote event handlers and overwrite file
- Push – Upload remote event handlers and overwrite
- Start – Start the remote Function
- Stop – Stop the remote Function
- Watch – Watch the local directory and push event handlers when changes are detected
- Test – Run event handler unit tests
When you init functions on your local machine, there is a test stub file that is generated relative to the event handler file. The test stub is meant for you to write unit tests for the event handler using Mocha and Chai.
Each test is like 1 event handler execution. You supply an expected output based on a specific input. You can also pre-populate KV Store values for every test. Several of the Function packages are mocked out. The independent package for testing is pubnub-functions-mock. However this package is automatically included when you install pubnub-cli.
Creating event handlers is done in the portal. Go to https://admin.pubnub.com/ and click on your PubNub project. Next click Functions on the left, and create a Function.
Next, click on the Function and then the create button, to make a new Event Handler.
Once you have created all the event handlers in your module, you can use the CLI tool to update the code from your local machine. This way, you can edit the code in your own IDE or editor, keep the code in source control, and control deployment from a comfortable space.
Navigate to the directory of the project using your terminal on your local machine. If you have not already, install the Functions CLI using Node.js with npm i pubnub-cli -g. Next, run pubnub-cli init to align your local machine with the PubNub portal. You will be prompted for your email and password for your PubNub Account. Login and use the arrow and enter keys to select the Functions that you want to pull to your machine.
This creates a block.json file in your directory, and also a folder for each type of event handler that you made. The folders contain the event handler code and also a test stub file. For test reference, see this package.
Let's say you're underway with your Functions development, and you're ready to include CD/CD. Here I will explain an example for setting up Travis-CI with your Functions repository on GitHub.
A sample GitHub repo where this is implemented is hosted here.
Travis-CI
If you have not already, go to https://travis-ci.org/ and sign in with GitHub. Next you want to enable your repository to automatically trigger a Travis-CI run whenever you push to it. On the Travis website, click profile in the top right dropdown. Find the repository you want to automatically test and deploy from the list, and click the toggle to enable.
After this has been enabled, you should be able to see on the GitHub side too. Go to your GitHub repository web page, and click Settings and Integrations & services.
You should allow Travis to automatically configure.
Next, we can configure the Travis run settings using the .travis.yml file. This is a file that should be checked-in to your GitHub repository in the most parent directory.
My settings below use the Functions CLI to test the code with my unit test file. If the tests pass, the Travis job is successful. If the branch that was pushed to is the master branch, the code will automatically be deployed to PubNub after successful tests.
.travis.yml
language: node_js
node_js:
- "7"
## Install the CLI and login to PubNub using Travis secrets you set
before_script:
- npm install -g pubnub-cli
- pubnub-cli login -m $emailaddress -p $password
- pubnub-cli init -b 30414 -k 455019 -a 445818
## Test
script:
- pubnub-cli test -b 30414 -k 455019 -a 445818
## Only deploy if this is a master commit
## Also only if this is a push and not a pull-request opening
deploy:
skip_cleanup: true
provider: script
script: pubnub-cli push -b 30414 -k 455019 -a 445818
on:
branch: master
condition: $TRAVIS_EVENT_TYPE = push
In order for this to work, you need to use the block, app, and key flags to directly reference the block. This can be found in the info logs from the CLI when it is used in your local terminal, and also in the URL of the Function when you are viewing the page in the PubNub Dashboard.
/123/456/account/296139/app/328822/key/454669/block/30414/
It is also imperative that you add your PubNub username and password to the Travis-CI secrets with the variable names emailaddress and password. This is how Travis-CI will get access to your PubNub account.
To add secret variables to your Travis run, go to your Travis profile page and click on the project name. On the top right click more options and settings.
Toward the bottom of the page there is a UI to add your secret environment variables. Note that the special characters in your PubNub password may malfunction when referenced as shell variables. Make sure your special characters are escaped properly if necessary.
Once these are added, you're all done. Every push to a branch is tested. Every time you push to the master branch, your code is tested and deployed to PubNub, automatically!
Note that the Travis settings make sure that the job will only run after a pull request is merged into the master branch, to avoid deploying when a pull request is opened. The same goals can be accomplished using other CI/CD services. I hope this post brings sanity to your deploys with Functions.
