IDE Setup¶

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

IP and port where your instance of the SDK is installed.
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.

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.
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
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
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
- Edit Remote Host Settings
- Enter User name and Password
Database
- Click on the Database tab
- Edit Data Source Properties
- Enter the password provided in your Welcome Email
- Enter Data Source SSH Proxy User and Password
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:
- Add SSH Interpreter from your existing Shared Dev Env Deployment configuration
- Once Selected, PyCharm will ask if you want to Create or Move this server. Click Move
- Edit the Interpreter and Sync folders as follows:
  
  Interpreter: /home/<username>/sdk/.env/bin/python
  
  Sync folders: Set Remote path to /
  
  click Finish
  
  Your Project Interpreter should appear similar to this:
- Add the Project Interpreter to your Remote Debug Configuration, SDK Debug
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
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.

Make sure you have read through the getting started guide for Q2 Internal Dev
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+

Open up the Terminal window in Pycharm
Run pip install q2-sdk
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.

Visual Studio Code¶

Develop on a remote box¶

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

We’re going to be following the guide at https://code.visualstudio.com/docs/remote/ssh#_getting-started
- Install an OpenSSH compatible SSH client if one is not already present. See https://code.visualstudio.com/docs/remote/troubleshooting#_installing-a-supported-ssh-client
- Install Visual Studio Code.
- Install the Remote Development extension pack.
- Add SSH key authentication to the shared dev server - See https://code.visualstudio.com/docs/remote/troubleshooting#_configuring-key-based-authentication You should end up with a SSH config file that looks like below:
  Host q2-dev HostName sdk-shared-dev.q2devstack.com User <replace-with-your-username> LocalForward <replace-with-database-port> localhost:<replace-with-database-port>
Run Remote-SSH: Connect to Host... from the Command Palette (F1) and select the host q2-dev
Once connected to remote host, open folder to /home/<username>/sdk

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"
}

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"
            ]
        }
    ]
}

Your Visual Studio code is now setup to do remote development, enjoy!

Develop locally¶

This section is for Q2 employees.

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

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"
            ],
        }
    ]
}

Your Visual Studio code is now setup to do development and debugging!