Documentation

# Setup

The Kortical package has three pre-requisites:

  • Python (3.8 or 3.9 is recommended)
  • Docker (version 19.03.1+, experimental mode)
  • Kortical login credentials

The steps to install everything are detailed below; alternatively, you can set up the Kortical SDK Docker environment (see the bottom section).

# 1. Set up Python.

If you don't have Python 3.8 or 3.9, or have multiple versions, we recommend creating a Python virtual environment (opens new window) (venv):

    > which python3.9                                    
> <path-to-python3.9>/python3.9 -m venv venv          
> source venv/bin/activate                  

    > where python3.9
> <path-to-python3.9>/python3.9 -m venv venv
> copy "venv\Scripts\python.exe" "venv\Scripts\python3.exe"         
> venv\Scripts\activate.bat            

    // Make sure to add code blocks to your code group

    This example creates a venv called venv; to create with a different name, change the last parameter.

    # 2. Set up Docker.

    Make sure you have Docker installed (version 19.03.1 or greater) and that the application is running. Click the cog at the top right of Docker Desktop to bring up the settings screen, then Docker Engine. Ensure that experimental: true (i.e. your docker engine settings should look like this):

    {
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": true,
  "features": {
    "buildkit": true
  }
}
    Docker for Windows

    Getting Docker + Windows + Kortical SDK to work together is a bit trickier. In short, Kortical needs to be able to build Linux Docker images, even though we are on Windows. The way to do this is to use Windows Subsystem for Linux version 2 (WSL2) as a backend for Docker Desktop.

    Follow these steps in strict order:

    • In a command prompt, right click and select run as administrator. Install WSL (wsl —-install), then restart your machine.
    • Install a Linux distribution (wsl --install -d <Distribution Name>); for a list of options, run wsl --list --online. Set WSL2 and the desired Linux distribution as defaults (wsl --set-default-version 2 , wsl --setdefault <DistributionName>).
    • Only after the previous step is complete, install Docker Desktop for Windows. In settings —> resources —> WSL integration, choose the Linux distribution you installed. In settings —> Docker Engine, set “experimental” : ”true”.
    • Try running docker run hello-world and some other commands, everything should now work!

    More information on Docker + Windows:

    https://docs.docker.com/desktop/windows/wsl/ (opens new window) https://docs.microsoft.com/en-us/windows/wsl/install (opens new window)

    # 3. Set up Kortical.

    To install the latest version of Kortical and check that it has been installed correctly, run the following:

    pip install --upgrade kortical
kortical --help

    To be able to use most of Kortical, you need to enter your Kortical login details; these will be prompted when running any CLI commands, e.g:

    > kortical status
Please enter your system URL here:
https://platform.kortical.com/<company>/<system-name>

Please enter your login email:
darth.vader@kortical.com

Password:
************

    # Run Kortical in a Docker environment (advanced)

    Users with more complicated installations may encounter dependency conflicts with Kortical, so we have provided a Docker image inside which you can run Kortical. Setting this up is straightforward, assuming you already have Docker.

    First, pull the image (at time of writing, this is 2.1.0):

    > docker pull eu.gcr.io/kortical-package/kortical:<version>

    Next, start up a container (you must change the source path to a folder containing your apps):

    > docker run -d -it \
    --name kortical_environment \
    -v /run/host-services/ssh-auth.sock:/ssh-agent \
    -e SSH_AUTH_SOCK="/ssh-agent" \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --mount type=bind,source=/Users/owen/git/kortical_apps,target=/root/kortical_apps \  ### Alter this line!
    eu.gcr.io/kortical-package/kortical:<version>

> docker ps
CONTAINER ID   IMAGE                                           COMMAND     CREATED          STATUS          PORTS     NAMES
183eb9413e94   eu.gcr.io/kortical-package/kortical:<version>   "python3"   29 minutes ago   Up 29 minutes             kortical_environment

    Note

    For M1 Macs, add the option --platform linux/amd64 to the docker run command.

    The volume flag allows you to run Docker commands inside the container (required when deploying apps to Kortical). The bind mount grants access to your local files; this allows you to work from the container and see the changes on disk. In this example, we have bound just one app, but could easily bind the folder kortical_apps if there are multiple codebases.

    Finally, you can open a shell inside the container and run Kortical/Docker commands:

    > docker exec -it kortical_environment bash

> kortical status
Please enter your system URL here:
etc...

    ← Platform API →