Guide on how to deploy a CometD Node client to Windows Server

hosting-cometd-on-windows.md

Hosting CometD Clients on Windows Server (2019)

How to host and correctly run a Node CometD client on Windows Server (2019+) for connecting to a Salesforce instance in order to listen to Platform Events. These instructions are also specifically for accessing a Windows Server instance running in Azure.

Steps Followed

1. Set up Remote Desktop connection to get access to the server
   1. Download macOS Microsoft Remote Desktop client via the Mac App Store
   2. Ensure that you have the Windows AD credentials for the organization in order to allow you to log in
   3. Get the URL of the Workspace from your Admin
   4. Click "Add" button under the Workspaces tab
   5. Authenticate accordingly
   6. Double-click on the Desktop
2. Validate Node is installed on the server: node --version
   1. If it's not, see the section below on installing nvm on Windows Server and using it for Node version management
3. Validate git is installed on the server: git --version
   • Note: I largely used git for getting application code onto the server, so if you plan on getting your CometD client onto the server via another method, then feel free to ignore this step.
4. Install pm2 globally: npm i pm2 -g
   • Note that it does need to be installed globally, as pm2 doesn't usually operate in the context of just 1 project
5. Run npm root -g to determine the location of your globally-installed packages
6. Add the resulting directory to your PATH variable
   • Important Note: That command will likely produce something like C:\joturner\AppData\Roaming\npm\node_modules. To get this to work, you need to remove the node_modules from the directory path and then add it to your PATH variable. E.g., C:\joturner\AppData\Roaming\npm\
7. Create a new folder called pm2 at the following location: C:\etc\pm2
8. Create a new System-level environment variable called PM2_HOME pointing to this new directory
9. Get access to the application code that you're planning on running (I.e., get the code onto the machine)
   • In our case, I cloned a repo to the server using git
   • Important Note: If you're using my CometD Node Example as a starter, make sure that you generate a certificate or get the cert onto the Windows machine for valid OAuth2.0 JWT Bearer Token Flow authentication. Basically, make sure you set up whatever you need to in order to correctly authenticate to your Salesforce instance
10. Test that the application works. E.g., run npm start
11. Start the application via pm2: pm2 start NAME_OF_ENTRY_FILE.js
    1. Validate that the service is running via pm2 list
    2. Tail any logs from your application via pm2 logs
    3. If you need to stop the application, grab the ID from pm2 list and then run pm2 stop ID_OF_YOUR_APPLICATION
12. Ensure that the process restarts on system reboot. Unfortunately pm2 startup does NOT support Windows environments, so this gets a bit tricky... Basically, follow the instructions found here to get the pm2-installer service running (which the pm2 folks themselves recommend in their docs for running on Windows). At the time of this writing, it included the following steps:
    1. Stop all running pm2 processes
    2. Download and unzip the contents of the most recent version to your machine somewhere
    3. Open cmd as an Administrator
    4. Navigate to the pm2-installer directory
    5. Run npm run setup
       1. Inspect the contents of the cmd prompt to check to see if there are any warnings.
       2. If so, type N to stop the setup and instead run npm run configure. THEN run npm run configure-policy
       3. Then run npm run setup again
    6. Close all prompts you might have open (Git Bash, cmd, Powershell, etc...) and open another cmd prompt as an Administrator
    7. Navigate to the application root directory and start your app via pm2 again: pm2 start NAME_OF_ENTRY_FILE.js
    8. Run pm2 save
    9. Restart the server and check that pm2 (and your application) start up as expected
13. 🎉 Celebrate! You're done! 🎉

Installing git on Windows Server

Important Note: I'm very much a macOS person, therefore if some of the following seems overly simplified or odd, understand that I have very little experiencing developing and interacting with the CLI in a Windows environment.

1. Navigate to the Windows install page for git: https://git-scm.com/download/win
2. Download the most recent version for your architecture
3. Run the installer and follow the wizard for installing Git for Windows
4. Once installed, launch Git Bash which you'll use as your terminal in order to run git-based commands.
   • This terminal emulator will also have access to the other CLI tools that you have in your PATH

See the Related Reading Section for more posts related to installing git on Windows.

Misc. Notes

• Given that CometD isn't an application that will be accessible via the web, it doesn't need to be hosted via a web server

Related Reading

• Setting up MS Remote Desktop macOS Client
• Hosting NodeJS Apps via IIS on Windows Server
  • Given that this application isn't actually a web-application, likely won't need to follow these instructions. That said, interesting article nonetheless.
• Running NodeJS Apps via PM2 on Windows Server
  • This one is pretty barebones, and honestly doesn't add much that other pm2 posts outline
• Setting up and Running Node Applications via PM2
• Install Git on Windows
• PM2 Quickstart
• PM2 Startup Guide