text-adventure-llm/setup_guide.md

Setup Guide for Text-Based LLM Interaction System (Linux)

This guide describes a clean Linux-first setup (tested on Ubuntu/Debian). It removes macOS/Windows specifics and focuses on a reliable developer workflow with pyenv, virtual environments, Docker, and Portainer.

Prerequisites

• Git
• curl or wget
• build tools (gcc, make, etc.)
• Docker Engine and Docker Compose plugin

Recommended (optional but helpful):

• net-tools or iproute2 for networking diagnostics
• ca-certificates

On Ubuntu/Debian you can install Docker and the Compose plugin via apt:

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
# Allow running docker without sudo (re-login required)
sudo usermod -aG docker "$USER"

Installing pyenv (Ubuntu/Debian)

Install dependencies required to build CPython:

sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
  libffi-dev liblzma-dev

Install pyenv:

curl https://pyenv.run | bash

Add pyenv to your shell (bash; recommended on Linux):

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init --path)"' >> ~/.profile

# Interactive shells
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload your shell
source ~/.profile
source ~/.bashrc

Using zsh on Linux? Add to ~/.zprofile and ~/.zshrc instead:

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zprofile
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zprofile
echo 'eval "$(pyenv init --path)"' >> ~/.zprofile
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
source ~/.zprofile
source ~/.zshrc

Installing Python with pyenv

# List available Python versions
pyenv install --list

# Install a specific Python version (project default)
pyenv install 3.9.16

# Set it as your global default (optional)
pyenv global 3.9.16

Note: If you prefer a newer interpreter and your tooling supports it, Python 3.11.x also works well.

Creating a Virtual Environment

Choose ONE of the methods below.

Method 1: Using pyenv-virtualenv (recommended)

# Install pyenv-virtualenv plugin
git clone https://github.com/pyenv/pyenv-virtualenv.git "$(pyenv root)"/plugins/pyenv-virtualenv

# Initialize in your interactive shell
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
source ~/.bashrc

# Create and activate a virtual environment
pyenv virtualenv 3.9.16 text-adventure
pyenv local text-adventure   # auto-activates in this directory
# or activate manually
pyenv activate text-adventure

Method 2: Using Python's built-in venv

# Use the selected Python version in this directory
pyenv local 3.9.16

# Create and activate venv
python -m venv .venv
source .venv/bin/activate

Installing Project Dependencies

With your virtual environment active:

python -m pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Verifying Setup

# Check Python version
python --version

# Check installed packages
pip list

# Run basic tests
python test_system.py
# Optionally:
python test_llm_connection.py
python test_llm_exchange.py

Docker (Linux)

Docker provides a clean, reproducible environment.

Build and Run

# Build the image
docker build -t text-adventure .

# Run using host networking (Linux-only)
docker run -it --rm --network host -v "$PWD":/app text-adventure

Docker Compose (v2 CLI)

Update docker-compose.yml as needed. On Linux you may use host networking:

services:
  text-adventure:
    build: .
    network_mode: "host"   # Linux-only

Then:

docker compose up --build
# Run detached
docker compose up -d --build
# Stop and remove
docker compose down

Connecting to LM Studio from a container

LM Studio is assumed to run on the Linux host (default in config.py). Prefer using the special hostname host.docker.internal inside containers.

Option A (recommended when not using host network): add an extra_hosts mapping using Docker’s host-gateway:

services:
  text-adventure:
    build: .
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then in config.py, set:

self.LM_STUDIO_HOST = "host.docker.internal"
self.LM_STUDIO_PORT = 1234

Option B (Linux-only): use host networking (container shares host network namespace). In this case keep LM_STUDIO_HOST as 127.0.0.1 or the host’s IP address.

Fallback: If neither applies, you can use your Docker bridge gateway IP (often 172.17.0.1), but this can vary by system.

Connectivity quick check from inside the container:

docker compose exec text-adventure python - <<'PY'
import requests
import sys
url = "http://host.docker.internal:1234/v1/models"
try:
    r = requests.get(url, timeout=5)
    print(r.status_code, r.text[:200])
except Exception as e:
    print("ERROR:", e)
    sys.exit(1)
PY

Portainer Deployment (Linux)

Portainer simplifies Docker management via the web UI.

Prerequisites

• Portainer instance reachable (e.g., http://10.0.0.199:9000)
• Valid Portainer credentials
• Docker image available (local or registry)

Create a local env file and never commit secrets:

cp .env.example .env
# edit .env and set PORTAINER_URL, PORTAINER_USERNAME, PORTAINER_PASSWORD

Deploy

The script deploy_to_portainer.py deploys a single container using host networking, which works on Linux:

python deploy_to_portainer.py

You can also override environment variables:

export PORTAINER_URL=http://10.0.0.199:9000
export PORTAINER_USERNAME=admin
export PORTAINER_PASSWORD=yourpassword
python deploy_to_portainer.py

After deployment, verify connectivity to LM Studio using the container exec method shown above.

Troubleshooting (Linux)

• pyenv: command not found

  • Ensure the init lines exist in ~/.profile and ~/.bashrc, then restart your terminal:
    • eval "$(pyenv init --path)" in ~/.profile
    • eval "$(pyenv init -)" in ~/.bashrc

• Python build errors (e.g., "zlib not available")

  • Confirm all build deps are installed (see Installing pyenv).

• Virtual environment activation issues

  • For venv: source .venv/bin/activate
  • For pyenv-virtualenv: pyenv activate text-adventure

• Docker permission errors (e.g., "permission denied" / cannot connect to Docker daemon)

  • Add your user to the docker group and re-login: sudo usermod -aG docker "$USER"

• docker compose not found

  • Install the Compose plugin: sudo apt install docker-compose-plugin

• Container cannot reach LM Studio

  • If using extra_hosts: verify host-gateway mapping and LM_STUDIO_HOST=host.docker.internal in config.py.
  • If using host network: ensure LM Studio is listening on 0.0.0.0 or localhost as appropriate.
  • Try the connectivity check snippet above; if it fails, verify firewall rules and that LM Studio is running.

Notes

• The LM Studio address 10.0.0.200:1234 in config.py is a placeholder. Adjust it to your environment as described above.
• Do not commit your .env file. Use .env.example as a template.
• Use docker compose (v2) commands instead of the deprecated docker-compose (v1) binary.