dockerized-setup.rst

How to Set Up Dockerized Workspaces for Development

This document describes the steps necessary to setup the workspaces system in IntelliJ for development.

The workspaces systems is now dockerized, meaning it needs to run via Docker. While utilizing Docker comes with many advantages, it has also introduced complexity in the setup of IntelliJ for active development.

Table of Contents

• Initial Setup
• Set up Remote Python Interpreter
• Setup IntelliJ Docker-Compose Configuration (Optional)
• Debugging Workspaces
  • Debugging Workspaces Tests

Initial Setup

1. Make sure you have Docker Desktop installed and the Docker plugin enabled in IntelliJ. Also make sure you have the Python plugin installed and enabled.
2. Clone the repository from GitLab and import it into IntelliJ as a new project
3. Open IntelliJ's terminal and run

make clean
make build
docker compose -f docker-compose.local.yml up

This will build your local images and containers

Note: If you notice 'no such file or directory' errors with the docker compose command, try the following:

1. Cancel the docker compose command
2. Delete the pgdata directory
3. Run make reallyclean
4. Run make build again, followed by the docker compose command previously mentioned.

Set up Remote Python Interpreter

This is really a two step process. First, setting up the python interpreter which makes the requirements.txt packages accessible, and second, making the workspaces specific packages findable.

It would rather defeat the purpose of using docker for standardization if we then had to use a venv for python development. Fortunately, IntelliJ has a solution for this! We're going to connect to the python installation running in the docker containers for development.

1. Open :menuselection:`File --> Project Structure` and click on SDKs in the left hand menu.
2. Click the '+' at the top of the window and select 'Add Python SDK' from the drop down.
3. There should be an option on the left called 'Docker Compose', choose this option.
   1. You may need to create a new Server. Click 'New', make sure 'Docker for Mac' is selected and click 'OK'.
   2. Choose 'docker-compose.local.yml' as the only configuration file. You may need to add it.
4. Select a service (workflow or capability are suggested) to act as the python interpreter provider
5. Click 'OK'. IntelliJ will index the packages from the remote container.
6. Now click on 'Project' in the left hand menu and set the Project SDK to your new remote interpreter.
7. Now click 'Modules' and then 'Dependencies' and set the workspaces Module SDK to your remote interpreter.
8. Now go back to the 'Sources' tab of the workspaces module. You should see a list of directories. You will need to set the source locations in order for IntelliJ to pickup the packages and imports that belong to the workspaces project as well as the python imports from requirements.txt files.
   1. Example: In the displayed directory tree, navigate to services/capability/ and click on src/.
   2. Now click on the blue 'Sources' button at the top of the directory tree. The src/ directory should turn blue. This will identify services/capability/src as a source location to IntelliJ.
   3. Do this for each of the locations listed in the following picture:

Now all imported python and workspaces packages should be available for usage, and there should not be any red underlining on your import statements.

Setup IntelliJ Docker-Compose Configuration (Optional)

This step is optional as it can be run directly from the terminal command line. However, one plus to setting up a configuration is that you can access the container logs from within Intellij rather than needing to access them via Docker Desktop or terminal.

1. At the top of the main Intellij window there is a drop down menu that probably says something like 'Edit configurations...'.
2. Select 'Edit Configurations'
3. Click the '+' and select Docker and then Docker-compose. This will create a new run configuration.
4. Setup the configuration as in the following picture:

Now you should be able to run 'docker compose up' by simply selecting this configuration and clicking the green run arrow next to the drop down menu.

Please Note that you can't use the debug option with this configuration!

Debugging Workspaces

Since debugging need to occur within an actively running capability or workflow server, we need to set up Pyramid servers that will enable this functionality. You will need to do this twice - once for capability and once for workflow.

1. As with the Docker-Compose configuration described above, you will need to create a new Pyramid Server configuration. Open Run/Debug Configurations, click '+' and select 'Pyramid Server'
2. Setup your configuration as in the following picture:

Please note the use of 'Use specified interpreter'! Since we need to attach the debugger to a running container - and since there are different containers for the capability and workflow servers - we need to use the remote interpreter for that specific container. If you do not have a remote interpreter set up for whichever server you want to debug, create one now.

You should now be able to debug workspaces! To use this do the following:

1. Make sure you've run docker compose up and that your containers are running
2. Set breakpoints at the lines you wish to investigate.
3. Select the pyramid server configuration for the service you wish to debug and click the green debug button. The specified debugger will attach itself to the container of the service.
4. You should now be able to step through the code.

Please note that the debugger only works if the pyramid server's --reload option is NOT used. If you make a code change you will need to relaunch the debugger to pick it up.

Also: Once you are done debugging, the debugger shuts down the attached container on exit. You will need to restart the container via docker compose -f docker-compose.local.yml up <service>

Debugging Workspaces Tests

To step through pytest using the debugger, set up a config under Python tests, like so:

Happy Developing!