Set Up a Local Dev Container ============================ To simplify your development experience, a VS Code `Development Container `_ (Dev Container) has been set up with a fully-featured development environment. `This guide `_ provides a good overview if this is your first time working with Dev Containers. Required Software for Local Dev Container ----------------------------------------- `Git `_ Git is a command-line tool for a version control system that manages changes in the code repository. The default settings during installation are sufficient. `Visual Studio Code (VS Code) `_ VS Code is the IDE we will use to write code. The default settings during installation are sufficient. `VS Code Remote-Containers extension pack `_ The Remote-Containers extension pack will enable VS Code to work with dev containers. `Docker `_ Docker is an open-source platform used to manage the provided pre-configured development container. The default settings during installation are sufficient. Windows Docker Desktop 2.0+ on Windows 10 Pro/Enterprise. Windows 10 Home (2004+) requires Docker Desktop 2.3+ and the WSL 2 back-end macOS Docker Desktop 2.0+ Linux Docker CE/EE 18.06+ and Docker Compose 1.21+. (The Ubuntu snap package is not supported.) Remote hosts: 1 GB RAM is required, but at least 2 GB RAM and a 2-core CPU are recommended. Getting everything ready ________________________ 1. Install all required software, above. 2. Accept a GitHub invitation to join the repository for the pre-configured development container hosted by **artificialinc** as an external collaborator. After accepting the invite, notify your Customer Success Manager. 3. Log into GitHub and create a GitHub Personal Access Token (classic) with the `repo` and `write:packages` scopes by following `these steps `_. .. image:: _static/gh_token_permissions.png Copy the token to a secure place; we'll use it later. .. note:: Why do we need a GitHub token? 💡 We store development services and libraries in the Cloud, and you will need secure rights to access development libraries and call Cloud services. 4. Log into your Artificial instance and create an Artificial Personal Access Token for secure API access. #. From Artificial, go to :menuselection:`Settings --> (user name) --> API Keys --> + Add`. #. Set a :guilabel:`Token Name` (i.e, “my_token”), and click :guilabel:`Create`. #. Copy the token to a secure place; we'll use it later. Repository setup ---------------- 1. Use Git to clone your Artificial Repository using the URL your Artificial Customer Success representative provided. :: $ mkdir artificial-sdk $ cd artificial-sdk $ git clone https://github.com/ 2. Create a :file:`secrets.yaml` file in the :file:`configs/` directory. It should live next to the :file:`config.yaml`. It must contain the following:: artificial: token: 3. Create a :file:`.env` file in the base project directory with your GitHub login and token created from the previous steps:: PYPI_USER= PYPI_PASSWORD= 4. Follow `these instructions `_ to make sure that your SSH keys are shared with the dev container. Launching the Dev Container --------------------------- 1. Open your project folder in VS Code (not a sub-folder). .. note:: 💡 You may have to sign into Git to enable some features of the dev container. If prompted, configure it according to your personal preferences with the help of `sharing git credentials `_. 2. If you see a popup dialog like this in VS Code, select :guilabel:`Reopen in Container` .. image:: _static/dev_container.webp If you don't see the popup dialog, open the Command Palette (:kbd:`F1` or :kbd:`Command+Shift+P`), and select :guilabel:`Dev Containers: Rebuild and Reopen in Container` to run the dev container. 3. If you see get popup dialogs about restarting, then follow the prompts to restart. .. note:: The first time you open and build the Dev Container, it might take some time (depending on your internet connection) to download the container image and install dependent libraries into the container. After the initial build of the container, opening the folder with the container afterward is significantly faster. .. note:: 💡 On Windows, you may run into issues building the Dev Container if your global git settings specify `CRLF` line endings. To fix this, run the following command in your terminal to set the `core.autocrlf` setting to `true`. For more information, see `configuring line endings `_. :: git config --global core.autocrlf true After the build is complete, you will have a functional dev environment with all the plugins and support libraries for developing workflows, actions, and client utilities. This includes extensions so you can easily write and debug Workflows in Artificial. Running your Adapter -------------------- The Dev Container has the necessary files to connect to the Artificial Cloud instance that will be used for development. You can run the code from the container by clicking the :guilabel:`Run and Debug` tab in VS Code and pressing the green :guilabel:`Run` button. .. image:: _static/run_and_debug.webp