(gettingstarted_page)=
# Installation

(installing_sec)=
## Installing

(api_key)=
### API Key
When you receive your license file, you should also receive an API key. This key will be used by package managers, e.g., `apt` or `homebrew`, to access software packages from Karana Dynamics.

### Ubuntu
 1. **Apt package manager one time setup (and Windows WSL2):**
    This step only has to be done the first time you are installing. Afterwards, you can skip this and just do steps 2 onward. 

    To make things simpler, you can set your [API key](api_key) to an environment variable via
    ```bash
    export API_KEY=<API_KEY_FROM_EMAIL>
    ```
    for `bash` or `zsh` and via `setenv API_KEY <API_KEY_FROM_EMAIL>` for `csh`. This only needs to be done for this step. This environment variable is not needed in subsequent steps.

    Set up the GPG signing key:
    ```sh
    curl -H "Authorization: Bearer $API_KEY" https://artifact-keeper.karanadyn.com/debian/karana-debian/gpg-key.asc | sudo gpg --dearmor -o /etc/apt/keyrings/karana-dynamics-debian.gpg
    ```

    Set up the `apt` authorization:

    ```sh
    sudo tee /etc/apt/auth.conf.d/karana-dynamics.conf > /dev/null << EOF
    machine artifact-keeper.karanadyn.com
    login token
    password $API_KEY
    EOF
    ```

    Set up the `apt` repository:
    ```sh 
    sudo tee /etc/apt/sources.list.d/karana-dynamics.sources > /dev/null << EOF 
    Types: deb
    URIs: https://artifact-keeper.karanadyn.com/debian/karana-debian
    Suites: stable
    Components: main
    Signed-By: /etc/apt/keyrings/karana-dynamics-debian.gpg
    EOF
    ```
 2. **Debian package (and Windows WSL2):** Run 
    ```
    sudo apt update && sudo apt install kdflex
    ``` 
    to install the {{ kdflex }} package.

 3. **Python:** Install the `Karana` Python package located at `/usr/share/Karana/python`. The recommended way is to do this is in a Python virtual environment. Please note that the Python version should match the version {{ kdflex }} is built against. For Ubuntu, this is Python 3.12. To do so, run the following (this will take a few minutes to complete)
    ```sh
    python3.12 -m venv --system-site-packages .venv 
    source .venv/bin/activate 
    pip install /usr/share/Karana/python
    ``` 

    The virtual environment can be deactivated at any time using the `deactivate` command, or re-activated at any time by running `source .venv/bin/activate`. Alternative ways to install the Python packages are described in the [Alternative Python package installation options](python_pkg_install_sec) section below.
 4. **License setup:** Please set the `KARANA_LICENSE_FILE` environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.
   * For `bash` or `zsh`, use
     ```bash
     export KARANA_LICENSE_FILE=/path/to/license/<user>.license
     ```
   * For `csh` use `setenv KARANA_LICENSE_FILE /path/to/license/<user>.license`

 5. **Verify installation:** Run 
    ```sh
    /usr/share/Karana/check_installation/check_installation
    ``` 
    to verify that the installation is working correctly. This should run a {{ kdflex }} example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as *python* generates *.pyc* files.

### MacOS
The macOS (experimental) build is a `homebrew` package for *macOS golden gate*.  
1. **Brew package manager one time setup**
    This step only has to be done the first time you are installing. Afterwards, you can skip this and just do steps 2 onward. If you do not already have `homebrew` set up, please do so by following the [homebrew setup instructions](https://brew.sh/).

     Create a brew tap for the {{ kdflex }} package and trust it by running 
     ```sh
     brew tap karana/packages https://tickets.karanadyn.com/general/homebrew-packages.git
     brew trust karana/packages
     ```
 2. **Install via Brew:** 
 
     Run the following to install the {{ kdflex }} package. This will require the [API key](api_key) you received in the email with your license.
     ```sh
     HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN=<API_KEY_FROM_EMAIL> brew install kdflex
     ```

     To make things simpler, you can set your [API key](api_key) to an environment variable in your shell configuration file
     ```bash
     export HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN=<API_KEY_FROM_EMAIL>
     ```
     for `bash` or `zsh` and via `setenv HOMEBREW_KARANA_ARTIFACT_KEEPER_TOKEN <API_KEY_FROM_EMAIL>` for `csh`, so you don't need to enter it when updating {{ kdflex }} in the future.

 3. **Python:** Install the `Karana` Python packaged located at `/opt/homebrew/share/Karana/python`. The recommended way is to do this is in a Python virtual environment. Please note that the Python version should match the version {{ kdflex }} is built against. For macOS, this is Python 3.14. To do so, run the following (this will take a few minutes to complete)
    ```sh
    python3.14 -m venv --system-site-packages .venv 
    source .venv/bin/activate 
    pip install /opt/homebrew/share/Karana/python
    ``` 

    The virtual environment can be deactivated at any time using the `deactivate` command, and re-activate at any time by running `source .venv/bin/activate`. Alternative ways to install the Python packages are described in the [Alternative Python package installation options](python_pkg_install_sec) section below.
 4. **License setup:** Please set the `KARANA_LICENSE_FILE` environment variable to the location of your license file. This can be done by running one of the following commands in your terminal, or adding the line to your shell configuration file.
   * For `bash` or `zsh`, use
     ```bash
     export KARANA_LICENSE_FILE=/path/to/license/<user>.license
     ```
   * For `csh` use `setenv KARANA_LICENSE_FILE /path/to/license/<user>.license`
 5. **Verify installation:** Run 
    ```sh
    /opt/homebrew/share/Karana/check_installation/check_installation
    ``` 
    to verify that the installation is working correctly. This should run a {{ kdflex }} example that creates a robot arm multibody model and 3D visualization for it. There may be a start up delay the first time as *python* generates *.pyc* files.

### Windows WSL

{{ kdflex }} can be run on a `Windows` system via `WSL`. Instructions on setting up `WSL` itself are available [here](https://learn.microsoft.com/en-us/windows/wsl/install). {{ kdflex }} installation instructions are the same as for `ubuntu` above.



### Next steps 
 You now have a working installation of {{ kdflex }}. The
next step would be to review the [Usage Guide](usage_guide) for an
overview of **kdFlex's** capabilities, API, and usage. You can explore
the Jupyter notebook tutorial examples included in the installation are described in the
[Examples](./examples.md) section.  These working examples illustrate the
use of **kdFlex's** Python API. The [Program Skeletons](procedures) area
summarizes the steps needed for setting up your own simulations, and the
[Recipes](recipes.md) area has details for specific steps that may be
needed. The online [kdFlex
Chatbot](https://portal.karanadyn.com/chatbot/) is another handy way to get
answers to your questions.
 
**Forum, Issue tracker:** You may want to create accounts on the online {{ kdflex }} [community forum](https://forum.karanadyn.com) and [issue tracker](https://tickets.karanadyn.com) for additional support resources.

### Documentation

  - [kdFlex Chatbot](https://portal.karanadyn.com/chatbot/)
  - [Examples](./examples.md)
  - [Usage Guide](usage_guide)
  - [Program Skeletons](procedures)
  - [Recipes](recipes.md)
  - [Documentation](https://portal.karanadyn.com/docs/)
  - [Concepts](concepts)
  - [Spatial Operator Algebra (SOA) theory (book)](https://link.springer.com/book/10.1007/978-1-4419-7267-5)

  - **Working with C++:** See the [C++ and Python layers](cpp_python_sec) section for details about how to build and use your application with {{ kdflex }}.

### Upgrading
To upgrade {{ kdflex }} to a newer version, you can repeat the instructions given in steps 1 and 2 above in the [Installing](installing_sec)
 section. This will remove the old version of {{ kdflex }} and install the new version. In addition, it will update the Python dependencies if required.

### Docker image

This section is for users interested in running the *Ubuntu* {{ kdflex }}
build on a different *Linux OS*.  The following describes the process
for creating a `docker` container to host {{ kdflex }}. The instructions
below assume that you are already familiar with basic `docker` usage. 
Docker  documentation is available
[here](https://docs.docker.com/).

The `Dockerfile` below can be used to build a basic container with
kdFlex installed. This should be built with the {{ kdflex }} *DEB* package
and license file in the same directory as the Dockerfile.

```Dockerfile
# Use Ubuntu 24 image
FROM ubuntu:24.04

# Set the shell to /bin/bash
SHELL ["/bin/bash", "-ec"]

# Set LANG
ENV LANG="C.UTF-8"

# Update apt update
RUN apt update

# Install kdFlex
COPY ./kdflex*.deb /tmp
RUN apt install -y --fix-broken /tmp/kdflex*.deb

# Install Python dependencies 
RUN (cd /opt && python3 -m venv --system-site-packages .venv && source .venv/bin/activate && pip install /usr/share/Karana/python)

# Add source command to bashrc so the venv is automatically sourced
RUN echo "source /opt/.venv/bin/activate" >> ~/.bashrc

# Copy license file to /opt
COPY ./*.license /opt

# Add license file to bashrc
RUN echo "export KARANA_LICENSE_FILE=`ls /opt/*.license | head -n 1`" >> ~/.bashrc
```

The image can be built by running the following command:

```sh
docker build -f Dockerfile -t kdflex:latest .
```

The image can be run using:

```sh
docker run --net=host -ti kdflex:latest bash
```

The `--net=host` is added to map ports from the docker container to the local machine. This allows one to view the graphics, data plots, etc. by connecting to the appropriate URL with a web browser. The image above does not contain any logic to forward graphics applications from the docker image to the localhost, so bringing up a local window via the electron app is not an option from within the container as written above. Doing so is possible, but is OS and machine specific.

### Known issues

- When using web browsers on `Windows` operating systems for remote
  viewing of {{ kdflex }} 3D graphics, render updates do not work properly
  for `Chrome` based browsers such as `Chromium` and `Edge`. `Firefox`
  does work properly.

(python_pkg_install_sec)=
### Alternative Python package installation options

The following describe alternative options (instead of the recommended
virtual environment option described in the [Installing](installing_sec) section)
for installing the Python packages needed by {{ kdflex }}:

   1. **User local installation:** Install the requirements for your user by running 
      ```sh
      pip install --break-system-packages /usr/share/Karana/python
      ``` 
      or 
      ```sh
      pip install --break-system-packages /opt/homebrew/share/Karana/python
      ``` 
      if on macOS. This will install the packages to locally. You will likely need to add `~/.local/bin` to your path if it is not on there already, e.g., for `bash` run 
      ```sh
      export PATH=~/.local/bin:$PATH
      ``` 
      to do it for the current terminal session or add the export line to your shell configuration file.
   2. **System level installation: (Ubuntu only)** (CAUTION: This will modify the system-wide Python install so please use with care.) This should not be done on macOS, as the system Python version is too old to work with {{ kdflex }}. Install the requirements at the system level by running 
      ```sh
      sudo pip install --break-system-packages /usr/share/Karana/python
      ``` 
      This may require uninstalling some Python packages installed via `apt` with conflicting versions. This can be done using 
      ```sh
      sudo apt remove <package_name>
      ``` 

### Installing to alternative location
It is rare, but sometimes users will want to install the {{ kdflex }} package to an alternative location. For Ubuntu, one can download the `deb` file using
```sh
apt download kdflex
```
and then use `dpkg` to install to an alternative location. 

For macOS, one can use 
```sh
brew fetch kdflex
brew --cache kdflex
```
to download the `.tar.gz` file and get its location on the filesystem. Then, one can `untar` it to unpack it in a location of their choosing.