1.Environment Setup & Installation
Before writing any code, you need a properly configured environment. Jesse is a self-hosted framework with specific dependencies, and your choice of installation method will affect how you manage updates, handle data persistence, and deploy to production. This chapter covers the two primary approaches: containerized deployment via Docker (fastest and most consistent), and native installation on Ubuntu, macOS, and Windows (better for deep customization and IDE integration). We will finish by configuring the environment variables that govern database connections, security, and exchange API access.
Requirements Overview
Jesse requires a stack consisting of Python (versions 3.10 through 3.13), PostgreSQL (version 10 or higher), and Redis (version 5 or higher). The framework uses PostgreSQL for persistent storage of candle data, backtest results, and trading history, while Redis handles caching, message queuing, and inter-process communication during live trading sessions. You have two distinct paths to satisfy these dependencies: Docker, which bundles everything into pre-configured containers, or a native setup where you install each component directly on your operating system.
Docker Container Setup
Docker is the recommended approach for beginners and production deployments alike. It eliminates version conflicts between system libraries and ensures that your development environment matches your production environment exactly. Jesse ships with a complete Docker configuration in every new project, meaning you can have a running instance in minutes without manually configuring PostgreSQL or Redis.
To begin, ensure Docker is installed. On macOS or Windows, install Docker Desktop. On Ubuntu, run the installation script provided by Docker:
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
Once Docker is available, create a new Jesse project by cloning the official template repository. This template contains the docker directory with pre-configured docker-compose.yml files:
git clone https://github.com/jesse-ai/project-template my-bot
cd my-bot
cp .env.example .env
Navigate to the docker directory and start the containers. The -d flag runs the services in detached mode, allowing you to close the terminal without stopping Jesse:
cd docker
docker compose up -d
The first execution downloads the necessary images, which may take several minutes. Subsequent starts are nearly instantaneous. Once running, the dashboard is available at http://localhost:9000. To stop the services without removing data, use docker compose stop. To update Jesse to a newer version, pull the latest images and restart:
docker compose stop
docker compose pull
docker compose up -d
One significant advantage of the Docker approach is database persistence. The PostgreSQL data is stored in a Docker volume, meaning it survives container restarts. If you run multiple Jesse instances (for example, to trade different accounts or strategies simultaneously), you can share a single database volume across instances by declaring it as external in your docker-compose.yml:
volumes:
postgres-data:
external: true
Ubuntu System Setup
If you prefer native installation on Ubuntu—common for remote servers or development workstations—you must install Python, PostgreSQL, and Redis manually. This approach gives you finer control over resource allocation and makes it easier to integrate with system monitoring tools.
For fresh Ubuntu 22.04 installations, Jesse provides an automated stack installer that handles all dependencies:
source <(curl -fsSL https://raw.githubusercontent.com/jesse-ai/stack-installer/master/ubuntu-22.04.sh)
If you cannot use the automated script, manual installation is straightforward. Begin with Miniconda to isolate Python dependencies. Download and install Miniconda, ensuring you type "yes" when prompted to initialize conda:
bash Miniconda3-latest-Linux-x86_64.sh
Create a dedicated environment for Jesse using Python 3.12 and activate it:
conda create --name jesse python=3.12
conda activate jesse
Next, install PostgreSQL and create the database and user. Jesse expects a database named jesse_db and a user named jesse_user with full privileges:
sudo apt-get install postgresql postgresql-contrib
sudo -u postgres psql -c "CREATE DATABASE jesse_db;"
sudo -u postgres psql -c "CREATE USER jesse_user WITH PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE jesse_db TO jesse_user;"
sudo -u postgres psql -c "ALTER DATABASE jesse_db OWNER TO jesse_user;"
Install Redis via apt-get:
sudo apt-get install redis-server
Crucially, when using native installation rather than Docker, you must modify the .env file in your project root. Change the default values of POSTGRES_HOST and REDIS_HOST from postgres and redis (the Docker container names) to localhost:
POSTGRES_HOST=localhost
REDIS_HOST=localhost
macOS System Setup
macOS users typically employ Homebrew for system dependencies and Miniconda for Python management. This combination provides clean separation between system Python and Jesse's requirements.
First, install Homebrew if it is not already present:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Install Miniconda, selecting the appropriate architecture for your machine. For Apple Silicon (M1/M2/M3/M4):
mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
For Intel-based Macs, replace arm64 with x86_64 in the URL. Initialize conda and create the Jesse environment:
source ~/miniconda3/bin/activate
conda init --all
conda create --name jesse python=3.12
conda activate jesse
Install PostgreSQL and Redis via Homebrew. Note that Jesse requires PostgreSQL 17 or compatible:
brew install redis postgresql@17
Create the database and user using the PostgreSQL CLI. The commands mirror those used on Ubuntu, creating jesse_db and jesse_user with appropriate ownership:
psql postgres
CREATE DATABASE jesse_db;
CREATE USER jesse_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE jesse_db to jesse_user;
ALTER DATABASE jesse_db OWNER TO jesse_user;
\q
As with Ubuntu, you must update your .env file to use localhost for database and Redis hosts rather than the Docker service names.
Windows System Setup
Windows installation requires more steps due to the lack of native Redis support. The recommended approach uses Windows Subsystem for Linux (WSL) for Redis, while running Python and PostgreSQL natively on Windows.
Begin by installing Miniconda in PowerShell:
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o .\miniconda.exe
start /wait "" .\miniconda.exe /S
del .\miniconda.exe
Create and activate the Jesse environment:
conda create --name jesse python=3.12
conda activate jesse
For Redis, enable WSL and install Ubuntu 20.04 from the Microsoft Store. Open PowerShell as Administrator and run:
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
After rebooting and setting up Ubuntu, install Redis within the WSL environment:
sudo apt-get update
sudo apt-get install redis-server
redis-server
You must start the Redis server manually after each system reboot, or configure it as a service. Keep the WSL terminal running, or consider using Memurai as an alternative Redis implementation for Windows, though note that the free version requires restart every ten days.
For PostgreSQL, download the installer from the official PostgreSQL website (version 11.2 or higher). During installation, save the superuser password. After installation, add PostgreSQL to your system PATH by editing the environment variables and including the bin directory (for example, C:\Program Files\PostgreSQL\12\bin).
Create the database using the Windows Command Prompt:
psql -U postgres
CREATE DATABASE jesse_db;
CREATE USER jesse_user WITH PASSWORD 'password';
GRANT ALL PRIVILEGES ON DATABASE jesse_db to jesse_user;
ALTER DATABASE jesse_db OWNER TO jesse_user;
\q
Finally, install Cython, which Jesse requires for compiling performance-critical components:
pip install cython
Environment Variables Config
Regardless of your installation method, Jesse requires a .env file in your project root to store sensitive configuration and environment-specific settings. This file contains database credentials, Redis connection details, dashboard security settings, and exchange API keys.
The minimal configuration for a Docker setup uses service names as hosts, while native installations use localhost. A typical .env file includes:
PASSWORD=your_secure_dashboard_password
APP_PORT=9000
POSTGRES_HOST=postgres
POSTGRES_NAME=jesse_db
POSTGRES_PORT=5432
POSTGRES_USERNAME=jesse_user
POSTGRES_PASSWORD=password
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
For native installations, remember to switch the hosts:
POSTGRES_HOST=localhost
REDIS_HOST=localhost
The PASSWORD field secures the web dashboard. Set this to a strong, generated password, especially if exposing the dashboard to network interfaces beyond localhost. The APP_PORT defaults to 9000; change this if the port is already occupied or if running multiple instances on the same machine.
When preparing for live trading, you will add exchange-specific API keys to this file. The framework supports multiple exchanges including Binance, Bybit, Coinbase, and others, each requiring specific key formats. For example, Binance Futures requires:
BINANCE_PERPETUAL_FUTURES_API_KEY=your_key_here
BINANCE_PERPETUAL_FUTURES_API_SECRET=your_secret_here
Similarly, Bybit configurations distinguish between USDT perpetual, USDC perpetual, and spot markets, each with separate key variables.
Application settings that are not sensitive—such as optimization parameters, logging levels, or notification preferences—are managed through the dashboard's settings interface rather than the .env file. Access these via the gear icon in the top-right corner of the dashboard. Changes made through the UI are saved automatically and persist across sessions, though they do not affect currently running trading sessions until restarted.
With your environment configured and the .env file properly set, you are ready to launch Jesse. If using Docker, the containers are already running. For native setups, execute jesse run within your activated conda environment and navigate to http://localhost:9000. The dashboard should load, indicating successful database and Redis connectivity.
In the next chapter, we will create your first Jesse project, explore the directory structure, generate a strategy file, and execute an initial backtest to verify that data flows correctly through the system.