IDE Setup

Welcome to the Q2SDK! As part of the onboarding process, you should have been provided a few things:

  1. IP and port where your instance of the SDK is installed.
  2. Online URL with credentials to see the results of your work

Setting up an IDE

You may find it easier to work with the SDK in a modern IDE with code completion, highlighting, and other useful features. Our preferred editor at Q2 is PyCharm. It does everything you would expect from a powerful IDE alongside sophisticated remote debugging support. For a best-in-class editor that allows a quick start with minimal custom setup, PyCharm is the right choice.

Prefer Visual Studio Code, Eclipse, Vim, etc.? No problem, but we won’t be able to provide as much assistance. We’ve provided guides for PyCharm and VSCode setup below.

PyCharm

Develop on a remote box

This section is for SDK clients using a Q2-provided stack.

Note

The remote configuration is only an option in the professional version of PyCharm, and is currently unavailable in community edition. The trial version is what you want if you do not already have a license.

  1. First, ensure you have already connected to the shared dev box with ssh using your method of choice (ssh on *nix. For Windows, refer to Windows SSH Installation) and changed your password.

    • ssh sdk-shared-dev.q2devstack.com: your username is your first initial and last name, and the password will be test123.
    • Be sure to grab your port number for your stack by running echo $ANTILLES_SERVER_PORT. This will be needed in the next step.
  2. Visit http://sdk-shared-dev.q2devstack.com/pycharm_setup to obtain your PyCharm settings zip file.

    • Enter your user name
    • Enter your stack name
    • Enter your port number
  3. On your local workstation, create a new directory you want use as your SDK_Cloud PyCharm project, and cd into this directory.

    • Unzip the contents of the zip file into this directory
  4. You will need to open your PyCharm project, and input your SDK user name and password in a couple places.

    Note

    Be sure to check the boxes to Save/Remember passwords where applicable

    Remote Host

    • Click on the Remote Host tab
    _images/pycharm-remotehostpointer.png
    • Edit Remote Host Settings
    _images/pycharm-shareddevconfig.png
    • Enter User name and Password
    _images/pycharm-shareddevsettings.png

    Database

    • Click on the Database tab
    • Edit Data Source Properties
    _images/pycharm-datasource_edit.png
    • Enter the password provided in your Welcome Email
    _images/pycharm-datasource_gen.png
    • Enter Data Source SSH Proxy User and Password
    _images/pycharm-datasource_ssh.png
  5. Configure your Project Interpreter for the Remote Python environment.

    So far, most settings have been automated for you. However, the following settings are out of the scope for your local PyCharm project directory, and require some additional manual configuration for a more complete IDE experience.

    A Remote Python Interpreter will allow PyCharm to read and execute code on the shared dev box from your workstation.

    Here are the remaining steps to configure your Python Interpreter:

    • Pycharm Preferences/Settings -> Project -> Project Interpreter
    • Add Interpreter by clicking on the settings cog:
    _images/pycharm-interpreter-cog1.png
    • Add SSH Interpreter from your existing Shared Dev Env Deployment configuration
    _images/pycharm-addssh-interpreter.png
    • Once Selected, PyCharm will ask if you want to Create or Move this server. Click Move
    _images/pycharm-mvsrv4ssh.png
    • Edit the Interpreter and Sync folders as follows:

      Interpreter: /home/<username>/sdk/.env/bin/python

      _images/pycharm-remote-interpreter-settings.png

      Sync folders: Set Remote path to /

      _images/pycharm-edit-sync-folders.png

      click Finish

      _images/pycharm-sshinterpreter-finish.png

      Your Project Interpreter should appear similar to this:

      _images/pycharm-interpreter-success.png
    • Add the Project Interpreter to your Remote Debug Configuration, SDK Debug

    _images/pycharm-debug-config.png
    _images/pycharm-interpreter-debug.png
  6. Please complete the following steps to make sure you are all set.

    If you are attending Q2 SDK Certification Training, we ask that you can perform the following to help ensure all participants receive maximum value while allowing the class to quickly become acquainted with the SDK, and have you leaving class well on your way to success for your institution:

    Note

    This next step will require your public SSH key to be added in Gitlab

    • Your SSH keys have already been generated for you as part of creating your SDK user

      cat ~/.ssh/id_rsa.pub

    • Copy/Paste your public SSH key into Gitlab

      • Click Profile -> Settings
      • Click on SSH Keys located on the side panel
      • Paste your SSH Key into the key box, and Add your key
    • Open a SSH terminal to sdk-shared-dev.q2devstack.com and run clone_from_gitlab && source ~/.bashrc on the shared dev box

    • Query your database using your PyCharm Database Connection

      • Right-Click on your Database Connection -> Open Console
      • Execute the following query, using your stackname, to ensure you can retrieve data from your database
      SELECT * FROM Q2DB_sdk_stackname.dbo.Q2_Group
      
    • Run SDK Debug to ensure you can run your server remotely by clicking the green ‘Play’ button

      _images/pycharm-play.png
  7. You should now be ready. Here’s two pieces to get you started:

    • Tools -> Deployment -> Browse Remote Host will show you files on the server. You can download and edit them locally by right clicking on them
    • Tools -> Start SSH Session -> <Your Deployment Name> will let you access the remote server from the command line. Handy for running commands in the Tutorial!

Develop locally

This section is for Q2 employees.

  1. Make sure you have read through the getting started guide for Q2 Internal Dev
  2. Let’s make a new project. Create New Project -> Pure Python.
    • Under Interpreter, choose “Create VirtualEnv”
    • Ensure that the python version you choose is at least 3.5+
_images/pycharm-local_create.png
  1. Open up the Terminal window in Pycharm

  2. Run pip install q2-sdk

  3. Under Run -> Edit Configurations

    • New Python Configuration

    • Script:

      • OSX / Linux: .env/bin/q2

      • Windows: .env\Scripts\q2.exe

        Note

        Older versions of the SDK may throw the following error on launch:

        SyntaxError: Non-UTF-8 code starting with '\x90' in file .env/Scripts/q2.exe on line 1, but no encoding declared; see http://python.org/dev/peps/pep-0263/ for details

        If you see this error, try using: .env\Scripts\q2-script.py

    • Script Parameters: run

    • Working directory: <full path to project root>

    • Environment Variables: Copy the following block into your clipboard, then paste it into the Environment Variables ‘…’ menu:

      HQ_URL='http://10.115.4.22/sdk_dev-hydra'
      CSR_USER='q2'
      CSR_PWD='2q'
      ABA='022222222'
      

Note

You can of course change any of these variables if they are not appropriate for you. These will point to our SDK dev environment.

_images/pycharm-local_run.png
_images/pycharm-copy_env_vars.png

Visual Studio Code

Develop on a remote box

This section is for SDK clients using a Q2-provided stack.

  1. We’re going to be following the guide at https://code.visualstudio.com/docs/remote/ssh#_getting-started

  2. Run Remote-SSH: Connect to Host... from the Command Palette (F1) and select the host q2-dev

  3. Once connected to remote host, open folder to /home/<username>/sdk

  4. Run Preferences: Open Remote Settings (SSH: q2-dev) from the Command Palette (F1), your remote machine setting.json should look like:

    {
        "python.pythonPath": ".env/bin/python",
        "python.linting.pylintEnabled": true,
        "terminal.integrated.shell.linux": "/bin/bash"
    }
    
  5. Run Debug: Open launch.json from the Command Palette (F1), your launch.json should look like:

    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "q2 run",
                "type": "python",
                "request": "launch",
                "program": "/usr/local/bin/q2",
                "args": [
                    "run"
                ]
            }
        ]
    }
    
  6. Your Visual Studio code is now setup to do remote development, enjoy!

Develop locally

This section is for Q2 employees.

  1. Make sure you have read through the getting started guide for Q2 Internal Dev

  2. Run Debug: Open launch.json from the Command Palette (F1), you should have or add a configuration in launch.json that looks like:

    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "q2 run",
                "type": "python",
                "request": "launch",
                "program": "${workspaceRoot}/.env/bin/q2",
                "args": [
                    "run"
                ],
            }
        ]
    }
    
  3. Your Visual Studio code is now setup to do development and debugging!