# Setup

## Prerequisites

Ensure the following prerequisites are met and dependencies are installed before proceeding.

**1.** [**Python 3.11+**](https://www.python.org/)

<details>

<summary>pyenv <em>(recommended)</em></summary>

Pyenv manages Python versions and project dependencies with the **pyenv-virtualenv** plugin.

1. Follow the installation steps for [pyenv](https://github.com/pyenv/pyenv#installation).
2. Follow the installation steps for [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv?tab=readme-ov-file#installation).

Python can be installed with pyenv in the following way:

```cli
pyenv install 3.11
```

</details>

**2.** [**Git**](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

**3.** [**Docker**](https://docs.docker.com/get-started/get-docker/)

**4.** [**pipx**](https://pipx.pypa.io/stable/installation/)

**5.** [**Poetry**](https://python-poetry.org/docs/#installation)

**6.** [**Cookiecutter**](https://github.com/cookiecutter/cookiecutter?tab=readme-ov-file#installation)

***

## Setting Up Your Project

Set up your project using the **Template**, a tool designed to simplify the creation of books.

### 1. Clone and Initialize

Clone the [Template](https://github.com/kognitos/bdk-template) from GitHub and initialize your project with Cookiecutter:

```bash
cookiecutter git+ssh://git@github.com/kognitos/bdk-template.git
```

Enter the following project details or press **Enter** to keep the defaults:

| Configuration           | Description                                                                                              | Default                             |
| ----------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Project Name**        | The name of your project.                                                                                | Sample Book                         |
| **Project Slug**        | A URL-friendly version of the project name. If not provided, this will be derived from the project name. | sample\_book                        |
| **Project Description** | A short description of the project.                                                                      | A short description of the project. |
| **Author Name**         | You or your organization's name.                                                                         | Kognitos                            |
| **Initial Version**     | Initial project version.                                                                                 | 0.1.0                               |

### 2. Enter Project Directory

Navigate into the new project directory. Replace `project_slug` with your own **Project Slug** from the previous step:

```
cd <project_slug>
```

### 3. Create a Virtual Environment *(recommended)*

We recommend creating a virtual environment to isolate and manage your project dependencies.

**1.** [**Configure Poetry**](https://python-poetry.org/docs/configuration/#virtualenvsin-project) **to create the virtual environment inside the project’s root directory:**

```
poetry config virtualenvs.in-project true
```

**2. Create a virtual environment:**

```
poetry env use 3.11
```

<details>

<summary>Setting your local pyenv version</summary>

If you are using pyenv and encounter the following error:

```
pyenv: python3.11: command not found

  The python3.11' command exists in these Python versions:
   3.11.11
```

Run the following command to set the local pyenv version for the current directory:

```cli
pyenv local 3.11
```

</details>

**3. Activate the virtual environment**

Run `poetry shell` ***or*** manually [activate the environment](https://python-poetry.org/docs/managing-environments/#activating-the-environment) using the following commands:

{% tabs %}
{% tab title="macOS/Linux" %}

```
source $(poetry env info --path)/bin/activate
```

{% endtab %}

{% tab title="Windows (PowerShell)" %}

```
Invoke-Expression (poetry env activate)
```

{% endtab %}
{% endtabs %}

> **Note:** To later exit the virtual environment later, run `deactivate`.

**4. Install dependencies**

```
poetry install
```