Snakepit Installation Guide

Complete installation instructions for all platforms with troubleshooting tips.

Prerequisites
Quick Start
Platform-Specific Installation
Python Environment Setup
Verification
Troubleshooting

Prerequisites

Required Software

Elixir: 1.18 or later
Erlang/OTP: 27 or later
Python: 3.8 or later (for Python gRPC adapter)
pip: Python package manager

Optional Tools

Docker: For containerized deployments
make: For running build scripts
git: For GitHub installation

Quick Start

1. Add Snakepit to Your Project

From Hex (Recommended):

# mix.exs
def deps do
  [
    {:snakepit, "~> 0.4.1"}
  ]
end

From GitHub (Latest):

def deps do
  [
    {:snakepit, github: "nshkrdotcom/snakepit"}
  ]
end

Then run:

mix deps.get
mix compile

2. Install Python Dependencies

Using pip:

# Navigate to your deps directory
cd deps/snakepit/priv/python

# Install required packages
pip install -r requirements.txt

Or install globally:

pip install grpcio>=1.60.0 grpcio-tools>=1.60.0 protobuf>=4.25.0 numpy>=1.21.0

3. Verify Installation

# Test Python dependencies
python3 -c "import grpc; print('gRPC:', grpc.__version__)"

# Run Snakepit tests
cd ../../..  # Back to your project root
mix test

Platform-Specific Installation

Ubuntu/Debian

1. Install System Dependencies

# Update package lists
sudo apt update

# Install Erlang and Elixir
sudo apt install -y erlang elixir

# Install Python 3 and pip
sudo apt install -y python3 python3-pip python3-venv

# Install build tools (optional, for compiling native extensions)
sudo apt install -y build-essential python3-dev

2. Verify Versions

elixir --version
# Elixir 1.18.4 (compiled with Erlang/OTP 27)

python3 --version
# Python 3.10.12 (or later)

pip3 --version
# pip 22.0.2 (or later)

3. Create Python Virtual Environment (Recommended)

# Create a virtual environment for your project
python3 -m venv .venv

# Activate it
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

4. Install Snakepit Python Dependencies

# If using deps/snakepit
cd deps/snakepit/priv/python && pip install -r requirements.txt

# Or install packages directly
pip install grpcio>=1.60.0 grpcio-tools>=1.60.0 protobuf>=4.25.0 numpy>=1.21.0

Ubuntu-Specific Notes

Python 3.8 on older Ubuntu: Use deadsnakes PPA

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.10 python3.10-venv python3.10-dev

Erlang/Elixir from Erlang Solutions: For latest versions

wget https://packages.erlang-solutions.com/erlang-solutions_2.0_all.deb
sudo dpkg -i erlang-solutions_2.0_all.deb
sudo apt update
sudo apt install esl-erlang elixir

macOS

1. Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Dependencies

# Install Erlang and Elixir
brew install erlang elixir

# Python 3 comes with macOS, but install latest version
brew install python@3.11

# Verify installations
elixir --version
python3 --version

3. Create Virtual Environment

# Create virtual environment
python3 -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Upgrade pip
pip install --upgrade pip

4. Install Python Dependencies

cd deps/snakepit/priv/python
pip install -r requirements.txt

macOS-Specific Notes

M1/M2 Macs: grpcio may require Rosetta or ARM-native builds

# If you encounter architecture issues:
arch -arm64 pip install grpcio grpcio-tools

Using asdf: For version management

brew install asdf
asdf plugin add erlang
asdf plugin add elixir
asdf plugin add python

asdf install erlang 27.0
asdf install elixir 1.18.4-otp-27
asdf install python 3.11.8

asdf global erlang 27.0
asdf global elixir 1.18.4-otp-27
asdf global python 3.11.8

Windows (WSL2)

Recommended: Use Windows Subsystem for Linux 2 (WSL2) with Ubuntu.

1. Enable WSL2

# Run in PowerShell as Administrator
wsl --install -d Ubuntu-22.04

2. Follow Ubuntu Instructions

Once in WSL2 Ubuntu, follow the Ubuntu/Debian instructions above.

3. WSL-Specific Configuration

# Ensure WSL can access localhost ports
# (Usually works by default in WSL2)

# If you encounter networking issues:
# Add to /etc/wsl.conf
[network]
generateResolvConf = false

# Then restart WSL from PowerShell:
# wsl --shutdown

Windows Native (Not Recommended)

While possible, native Windows installation is complex. WSL2 is strongly recommended for better compatibility.

Docker

1. Create Dockerfile

# Dockerfile
FROM elixir:1.18.4-otp-27-alpine

# Install Python and build dependencies
RUN apk add --no-cache \
    python3 \
    py3-pip \
    python3-dev \
    build-base \
    git

# Set working directory
WORKDIR /app

# Copy mix files
COPY mix.exs mix.lock ./
COPY config config

# Install Elixir dependencies
RUN mix local.hex --force && \
    mix local.rebar --force && \
    mix deps.get && \
    mix deps.compile

# Install Python dependencies
RUN pip3 install --no-cache-dir \
    grpcio>=1.60.0 \
    grpcio-tools>=1.60.0 \
    protobuf>=4.25.0 \
    numpy>=1.21.0

# Copy application code
COPY . .

# Compile application
RUN mix compile

# Expose gRPC port range
EXPOSE 50051-50151

# Run the application
CMD ["mix", "run", "--no-halt"]

2. Build and Run

# Build image
docker build -t myapp-snakepit .

# Run container
docker run -p 4000:4000 -p 50051-50151:50051-50151 myapp-snakepit

3. Docker Compose

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "4000:4000"
      - "50051-50151:50051-50151"
    environment:
      - MIX_ENV=prod
      - SNAKEPIT_GRPC_PORT=50051
    volumes:
      - ./config:/app/config
    restart: unless-stopped

Python Environment Setup

Option 1: Virtual Environment (Recommended)

Benefits: Isolated dependencies, no global pollution, reproducible

# Create virtual environment
python3 -m venv .venv

# Activate
source .venv/bin/activate  # Linux/macOS
# OR
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r deps/snakepit/priv/python/requirements.txt

# Deactivate when done
deactivate

Important: Remember to activate the venv before running your Elixir app:

source .venv/bin/activate && iex -S mix

Option 2: System-Wide Installation

Benefits: Always available, simpler

pip3 install --user grpcio grpcio-tools protobuf numpy

Option 3: Poetry (Python Project Management)

# Install poetry
curl -sSL https://install.python-poetry.org | python3 -

# Create pyproject.toml in your project root
cat > pyproject.toml << 'EOF'
[tool.poetry]
name = "myapp"
version = "0.1.0"

[tool.poetry.dependencies]
python = "^3.8"
grpcio = ">=1.60.0"
grpcio-tools = ">=1.60.0"
protobuf = ">=4.25.0"
numpy = ">=1.21.0"
EOF

# Install dependencies
poetry install

# Run your app with poetry environment
poetry run iex -S mix

Option 4: Conda/Miniconda

# Create conda environment
conda create -n myapp python=3.11

# Activate
conda activate myapp

# Install dependencies
pip install grpcio grpcio-tools protobuf numpy

Verification

1. Verify Elixir Dependencies

mix deps.get
mix compile

Expected output:

==> snakepit
Compiling 40 files (.ex)
Generated snakepit app

2. Verify Python Dependencies

python3 << 'EOF'
import sys
import grpc
import grpc_tools
import google.protobuf
import numpy

print("✅ Python version:", sys.version)
print("✅ gRPC version:", grpc.__version__)
print("✅ gRPC tools version:", grpc_tools.__version__)
print("✅ Protobuf version:", google.protobuf.__version__)
print("✅ NumPy version:", numpy.__version__)
print("\n🎉 All Python dependencies are installed correctly!")
EOF

Expected output:

✅ Python version: 3.11.8 (main, ...)
✅ gRPC version: 1.62.1
✅ gRPC tools version: 1.62.1
✅ Protobuf version: 4.25.3
✅ NumPy version: 1.26.4

🎉 All Python dependencies are installed correctly!

3. Run Tests

mix test

Expected output:

Running ExUnit with seed: ...
..........
Finished in X.X seconds
160 tests, 0 failures

Note: Tests will pass even without Python dependencies installed. Some tests mock Python interactions, and others gracefully handle missing Python servers.

4. Run Example

# Simple example (requires Python gRPC)
elixir examples/grpc_basic.exs

Expected output:

=== Basic gRPC Example ===

1. Ping command:
Ping result: %{"status" => "ok", "timestamp" => ...}

2. Echo command:
Echo result: %{"message" => "Hello from gRPC!", ...}
...

If you see ModuleNotFoundError: No module named 'grpc', Python dependencies are not installed correctly.

Troubleshooting

Issue: `No module named 'grpc'`

Symptom:

ModuleNotFoundError: No module named 'grpc'

Solutions:

Check Python path:

which python3
python3 -m pip list | grep grpc

Install in correct environment:

# If using venv
source .venv/bin/activate
pip install grpcio grpcio-tools

# If system-wide
pip3 install --user grpcio grpcio-tools

Verify installation:

python3 -c "import grpc; print(grpc.__file__)"

Issue: `grpcio` Compilation Fails

Symptom:

error: command 'gcc' failed with exit status 1

Solutions:

Ubuntu/Debian:

sudo apt install -y build-essential python3-dev
pip install --upgrade pip setuptools wheel
pip install grpcio

macOS:

xcode-select --install
pip install --upgrade pip setuptools wheel
pip install grpcio

Use pre-built wheels:

pip install --only-binary :all: grpcio grpcio-tools

Issue: Port Binding Errors

Symptom:

[error] Failed to bind to port 50051: already in use

Solutions:

Check for existing processes:

lsof -i :50051
# Or
netstat -tuln | grep 50051

Kill orphaned Python processes:
```
pkill -f grpc_server.py
```

Change port range in config:

config :snakepit,
  grpc_config: %{
    base_port: 60051,  # Use different port range
    port_range: 100
  }

Issue: Worker Startup Timeouts

Symptom:

[error] Worker startup timeout after 10000ms

Solutions:

Increase timeout:

config :snakepit,
  pool_startup_timeout: 30_000  # 30 seconds

Reduce pool size (for slower machines):

config :snakepit,
  pool_config: %{
    pool_size: 2  # Start with smaller pool
  }

Check Python server startup:

# Test Python server manually
cd deps/snakepit/priv/python
python3 grpc_server.py --port 50051

Issue: Elixir/Erlang Version Mismatch

Symptom:

** (UndefinedFunctionError) function X is undefined

Solutions:

Check versions:
```
elixir --version
```

Install correct versions:

# Using asdf
asdf install erlang 27.0
asdf install elixir 1.18.4-otp-27

# Or via package manager (see platform-specific sections)

Issue: Mix Dependency Conflicts

Symptom:

** (Mix) Dependency resolution failed

Solutions:

Clean and reinstall:

mix deps.clean --all
mix deps.get
mix compile

Check for version conflicts in mix.lock:
```
rm mix.lock
mix deps.get
```

Issue: Virtual Environment Not Activating

Symptom:

bash: .venv/bin/activate: No such file or directory

Solutions:

Create venv first:

python3 -m venv .venv
source .venv/bin/activate

Use full path:

source /full/path/to/.venv/bin/activate

Check Python venv module:

# Ubuntu/Debian
sudo apt install python3-venv

Issue: Permission Denied on Linux

Symptom:

Permission denied: '/usr/local/lib/python3.X/site-packages'

Solutions:

Use --user flag:

pip3 install --user grpcio grpcio-tools

Use virtual environment (recommended):

python3 -m venv .venv
source .venv/bin/activate
pip install grpcio grpcio-tools

Use sudo (not recommended):
```
sudo pip3 install grpcio grpcio-tools
```

Additional Resources

Snakepit Documentation: README.md
Elixir Installation: https://elixir-lang.org/install.html
Python Installation: https://www.python.org/downloads/
gRPC Python Quickstart: https://grpc.io/docs/languages/python/quickstart/
asdf Version Manager: https://asdf-vm.com/

Getting Help

If you encounter issues not covered here:

Check existing issues: https://github.com/nshkrdotcom/snakepit/issues
Open a new issue: Include:
- Platform (Ubuntu 22.04, macOS 14, etc.)
- Elixir version (elixir --version)
- Python version (python3 --version)
- Error messages (full output)
- Steps to reproduce
Community support:
- Elixir Forum: https://elixirforum.com/
- Elixir Slack: https://elixir-slackin.herokuapp.com/

Next Steps: After successful installation, see the Quick Start Guide for usage examples.

Next Page → Migration Guide (v0.5 to v0.6)

Snakepit Installation Guide

Table of Contents

Prerequisites

Required Software

Optional Tools

Quick Start

1. Add Snakepit to Your Project

2. Install Python Dependencies

3. Verify Installation

Platform-Specific Installation

Ubuntu/Debian

1. Install System Dependencies

2. Verify Versions

3. Create Python Virtual Environment (Recommended)

4. Install Snakepit Python Dependencies

Ubuntu-Specific Notes

macOS

1. Install Homebrew (if not already installed)

2. Install Dependencies

3. Create Virtual Environment

4. Install Python Dependencies

macOS-Specific Notes

Windows (WSL2)

1. Enable WSL2

2. Follow Ubuntu Instructions

3. WSL-Specific Configuration

Windows Native (Not Recommended)

Docker

1. Create Dockerfile

2. Build and Run

3. Docker Compose

Python Environment Setup

Option 1: Virtual Environment (Recommended)

Option 2: System-Wide Installation

Option 3: Poetry (Python Project Management)

Option 4: Conda/Miniconda

Verification

1. Verify Elixir Dependencies

2. Verify Python Dependencies

3. Run Tests

4. Run Example

Troubleshooting

Issue: No module named 'grpc'

Issue: grpcio Compilation Fails

Issue: Port Binding Errors

Issue: Worker Startup Timeouts

Issue: Elixir/Erlang Version Mismatch

Issue: Mix Dependency Conflicts

Issue: Virtual Environment Not Activating

Issue: Permission Denied on Linux

Additional Resources

Getting Help

Issue: `No module named 'grpc'`

Issue: `grpcio` Compilation Fails