Initial commit.
Basic docker deployment with Local LLM integration and simple game state.
This commit is contained in:
Aodhan Collins
283
setup_guide.md
Normal file
283
setup_guide.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
curl https://pyenv.run | bash
|
||||
```
|
||||
|
||||
Add pyenv to your shell (bash; recommended on Linux):
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
python -m pip install --upgrade pip setuptools wheel
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Verifying Setup
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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](docker-compose.yml) as needed. On Linux you may use host networking:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
text-adventure:
|
||||
build: .
|
||||
network_mode: "host" # Linux-only
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
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](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:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
text-adventure:
|
||||
build: .
|
||||
extra_hosts:
|
||||
- "host.docker.internal:host-gateway"
|
||||
```
|
||||
|
||||
Then in [config.py](config.py), set:
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# edit .env and set PORTAINER_URL, PORTAINER_USERNAME, PORTAINER_PASSWORD
|
||||
```
|
||||
|
||||
### Deploy
|
||||
|
||||
The script [deploy_to_portainer.py](deploy_to_portainer.py) deploys a single container using host networking, which works on Linux:
|
||||
|
||||
```bash
|
||||
python deploy_to_portainer.py
|
||||
```
|
||||
|
||||
You can also override environment variables:
|
||||
|
||||
```bash
|
||||
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](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](config.py) is a placeholder. Adjust it to your environment as described above.
|
||||
- Do not commit your [.env](.env) file. Use [.env.example](.env.example) as a template.
|
||||
- Use docker compose (v2) commands instead of the deprecated docker-compose (v1) binary.
|
||||
Reference in New Issue
Block a user