diff --git a/docs/source/_static/images/vscode_remote_containers.png b/docs/source/_static/images/vscode_remote_containers.png new file mode 100644 index 000000000..1ea66dd0f Binary files /dev/null and b/docs/source/_static/images/vscode_remote_containers.png differ diff --git a/docs/source/development/docker_vscode.rst b/docs/source/development/docker_vscode.rst new file mode 100644 index 000000000..011bce85f --- /dev/null +++ b/docs/source/development/docker_vscode.rst @@ -0,0 +1,72 @@ +:orphan: + +Using Docker for Desktop and VSCode to Develop Locally +====================================================== + +Environment Prerequisites +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Requirements: + +- git +- Docker Desktop (tested on MacOS - Intel only) +- VSCode +- VSCode Extensions: Docker (Microsoft), Remote - Containers (Microsoft) +- Already followed and have running the `ST2 docker-compose setup ` + +.. note:: + Make sure you set the configuration (through environment) for "export ST2_PACKS_DEV=CUSTOMPATH" `per the README instructions` + so that you mount a local dir to the container's pack.dev + +Overview +-------- + +.. note:: + This was only tested on MacOS 12.2.x (x86_64/Intel) with Docker Desktop for Mac 4.5 and VSCode 1.65 + +These instructions were originally developed to get around the issues of local development on MacOS. There are still some dependencies under +requirements.txt for building st2 libraries that are not compatible with MacOS (mainly pyinotify). The method described here lets us get +around these issues by leveraging VSCode Extensions and a local docker-compose setup of StackStorm. + +Instructions +------------ + +Your docker-compose should already be running with all of the st2 containers. Go ahead launch your VSCode application. + +Setup in VSCode +--------------- + +Open your Command Palette (Shift+Cmd+P on MacOS), and enter: ``Remote-Containers`` and look for ``Remote-Containers: Attach to Running Container...``. + +.. figure:: /_static/images/vscode_remote_containers.png + :align: center + +A list of running containers appear. Select ``/st2-docker_st2client-1`` (which is based on an st2actionrunner image, so don't worry if you see that later +instead of st2client). + +A new VSCode Window should pop up and begin attaching to the st2client container. You can verify by looking at the connection status in the lower-right corner +of VSCode. It should say ``Container stackstorm/st2actionrunner:latest"``. + +When you are running VSCode on remote systems or containers, it installs a local support package of VSCode. This means the extensions you have installed on your +local VSCode are not available. For our purposes here, we need to install the python extension(s) again. Go ahead and install the extensions you normally would +for python. + +Now let's add our development directories (that are mapped to a local directory). Since we are now attached to the container, we can access and develop directly +in the pack.dev directory. Go ahead and select ``Open Folder`` and then input ``/opt/stackstorm/packs.dev/``. + +``packs.dev`` is where you'll add the packs you want to develop. You can create a new folder ``myNewPack`` or you can ``git clone`` a template from the exchange. +You can also do this directory in the attached container, or locally in your mapped directory. + +The last thing we need to do and to point VSCode's python interpreter to the correct place. This enables the virtual environment context in VSCode which gives +us access to st2 libraries such as ``st2common``, ``st2reactor``, etc, making development much easier. + +Open your Command Palette again and enter: ``Python: Select Interpreter`` + +It may or may not automatically detect the system interpreter (which we do not want), but it's likely you will need to manually specify the correct path. +Select ``Enter interpreter path`` and type / point it to ``/opt/stackstorm/st2/bin/python``. Now VSCode should automatically set the interpreter path and detect +the st2 venv for the virtual environment. + +Once this is all complete, you are ready to develop on MacOS with full access to st2 libraries with intellisense and validation. + +.. note:: + Testing frameworks have not been tested using this method. diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst index a18c54c4b..2828f02cb 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -33,6 +33,10 @@ Another approach is to install StackStorm and all the dependencies from source o of your liking. For more information about this approach, see :doc:`Installing StackStorm from sources `. +If you are already running Docker / Docker Desktop, another option to develop locally is to +utilize the available extensions in VSCode to get setup. This works especially well for MacOS users. +For more information, see :doc:`Setting up VSCode & Docker Development` + General Contribution Guidelines ------------------------------- diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index d88b542b9..8dd614f8f 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -53,7 +53,7 @@ on Ubuntu, or ``sudo yum install curl nss`` on RHEL/CentOS. Then run this comman .. code-block:: bash - bash <(curl -sSL https://stackstorm.com/packages/install.sh) --user=st2admin --password=Ch@ngeMe + bash <(curl -sSL https://stackstorm.com/packages/v3.6/install.sh) --user=st2admin --password=Ch@ngeMe This is an opinionated installation of |st2|. It will download and install all components, as per the :doc:`single host reference deployment <./overview>`. It assumes that you have a clean, basic diff --git a/docs/source/upgrade_notes.rst b/docs/source/upgrade_notes.rst index 9904649eb..dc44a5019 100644 --- a/docs/source/upgrade_notes.rst +++ b/docs/source/upgrade_notes.rst @@ -25,6 +25,13 @@ Upgrade Notes API action DELETE method with ``{"remove_files": false}`` or no additional argument in json body will remove only action database entry. +* systemd generators for ``st2api``, ``st2auth`` and ``st2stream`` socket files have replaced + the static ``.socket`` files. ``st2.conf`` has become the authoritative source for controlling + the IP address and port the service will listen on. This gives a more consistent and intuitive + means of configuring these services. If you previously configured these services by directly + modifying the ``.socket`` file or using the ``DAEMON_ARGS`` environment variable, they are no + longer referenced and ``st2.conf`` will need to be updated with the desired ip/port. + .. _ref-upgrade-notes-v3-5: |st2| v3.5 diff --git a/version.txt b/version.txt index 1009f663a..d70c8f8d8 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.6dev +3.6