Version 3.2 Documentation
Blog · API · VSCode · IDE · Debugging · Tutorial · Subscribe Click to subscribe to insights
Subscribe Click to subscribe to insights

Remote API debugging with VS Code

2022-01-24, by Dariusz Suchojad

  • Each Zato environment ships with default configuration that lets its servers be started from a Visual Studio Code's debugger

  • Servers started in this way can run remotely, e.g. your local IDE may be on Mac or Windows while your Zato servers will be in a remote Linux instance. This will still let you debug your services deployed remotely.

  • It does not matter whether the server is under Docker or if it runs in a Linux VM directly

  • This article contains step-by-step instructions on how to start a Zato server in such a manner and how to debug your code remotely from VS Code

Prerequisites

  • Ensure that your remote Zato server runs in a Linux system that has at least 2 CPUs and 2 GB of RAM. If you use AWS, a medium instance will be the correct one to choose.

  • Make sure that there is SSH connectivity between your localhost and the remote Linux server, that is, you can ssh into the system where the Zato server is. As a reminder, if you use Docker Quickstart, the default port is 22022.

  • If the server runs in a Docker Quickstart instance, there are no further prerequisites and you can skip to the next section

  • If you created a Zato cluster yourself, check if these two files exist:

    /path/to/your/environment/.vscode/launch.json
/path/to/your/environment/.vscode/settings.json

  • If the files do not exist, download them here: launch.json and settings.json

  • Once downloaded, save them to the locations above; if the .vscode directory does not exist, create it. The end result should be that if, for instance, your environment is in /opt/zato/env/dev, the files will go to /opt/zato/env/dev/.vscode.

SSH connections in VS Code

  • In VS Code, install an extension called Remote - SSH

  • After you install it, there will be a new button available in the bottom-left hand side corner of your IDE. The button will let you open SSH connections. Click it and then click "Connect to Host"

  • Choose the host where your Zato server is and the IDE will open a new window to connect to that host using SSH. Enter SSH credentials if necessary. Note that you will be in a new IDE window now.

Opening a remote environment

  • Once you are connected in a new window, choose "Open Folder", select the directory where your environment is and click OK

  • Under Docker Quickstart, the path will be /opt/zato/env/qs-1/. In other environments, navigate to your environment's path accordingly.

  • After opening the remote directory with a Zato environment, your IDE window will look like below:

Starting the server

  • Click the Run and Debug icon:

  • Click the play icon next to the Remote Zato Main option:

  • The IDE will work now on installing all of its own components in the remote Linux server - that may take a couple of minutes the first time around. The process is CPU-intensive which is why 2 CPUs are a prerequisite.

  • If VS Code tells you that its Python IDE extension is not installed in the remote SSH system, choose to install it over SSH. This may also take a couple of minutes.

  • Allow for some time until the IDE completes the installation of its remote components - there will be feedback provided in the IDE window's footer. Once they are installed, proceed to the next section below.

Deploying a test service

  • Save the code below as demo.py and hot-deploy it in the now-already-started remote server. Note the highlighted line, we are going to add a breakpoint to it soon.
# -*- coding: utf-8 -*-

# Zato
from zato.server.service import Service

class MyService(Service):
    def handle(self):
        msg = 'Hello, I am a demo service'
        self.logger.info(msg)

Debugging a service

  • In the IDE, find the deployed service on a remote server under the path of /path/to/server/work/hot-deploy/current/demo.py and open it:

  • Add a breakpoint in line 9, as indicated below:

  • Invoke the service in any way you prefer, e.g. through REST, Dashboard or from command line

  • The debugger will stop at line 9, showing the local variables, the call stack and other details, exactly as if it was a local server


Congratulations! This concludes the process, everything is set up, you can debug your Zato API services remotely now.

More blog posts➤