(gettingstarted_page)=
# Installation

(installing_sec)=
## Installing

### Ubuntu
Download the [ubuntu 24 kdFlex Debian file](https://portal.karanadyn.com/download) and 
 1. **Debian package (and Windows WSL2):** Run 
    ```sh
    sudo apt update && sudo apt install ./kdflex-*-Linux.deb
    ``` 
    to install the {{ kdflex }} package.
 2. **Python dependencies:** Install the Python requirements located in `/usr/share/Karana/requirements.txt`. 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 --upgrade -r /usr/share/Karana/requirements.txt
    ``` 

    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.
 3. **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`

 4. **Verify installation:** Run 
    ```sh
    cd /usr/share/Karana/Tutorials/example_urdf &&  python3 notebook.py
    ``` 
    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 is a `homebrew` package for *macOS
sequoia*.  Since the files require login access, you will need to create
a *brew tap* yourself (instructions below). To begin, download *macOS
sequoia* {{ kdflex }} package from the [downloads
page](https://portal.karanadyn.com/download). Then:
 1. **Install via Brew:** If you do not already have `homebrew` set up, please do so by following the [homebrew setup instructions](https://brew.sh/).
 
     a. **Brew tap:** Create a brew tap for the {{ kdflex }} package by running 
     ```sh
     brew tap-new karana/kdflex
     ```
        
     b. **Brew formula:** Untar the `*.tar.gz` file from the [downloads page](https://portal.karanadyn.com/download) into `/opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula`. From the directory where you originally downloaded the files, run 
     ```sh
     tar -vxf kdflex*.tar.gz -C /opt/homebrew/Library/Taps/karana/homebrew-kdflex/Formula
     ```
        
     c. **Brew install:** Run the following to install the {{ kdflex }} package:
     ```sh
     brew install karana/kdflex/kdflex
     ```

 2. **Python dependencies:** Install the Python requirements located in `/opt/homebrew/share/Karana/requirements.txt`. 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 --upgrade -r /opt/homebrew/share/Karana/requirements.txt
    ``` 

    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.
 3. **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`
 4. **Verify installation:** Run 
    ```sh
    cd /opt/homebrew/share/Karana/Tutorials/example_urdf  &&  python3 notebook.py
    ``` 
    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 instruction 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 --upgrade -r /usr/share/Karana/requirements.txt)

# 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 -r /usr/share/Karana/requirements.txt
      ``` 
      or 
      ```sh
      pip install --break-system-packages -r /opt/homebrew/share/Karana/requirements.txt
      ``` 
      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 -r /usr/share/Karana/requirements.txt
      ``` 
      This may require uninstalling some Python packages installed via `apt` with conflicting versions. This can be done using 
      ```sh
      sudo apt remove <package_name>
      ``` 
