Simplify Python setup for non-developer users

[dguido]

Problem

The current Python setup process requires multiple steps and understanding of virtual environments, which can be intimidating for non-developer users who just want to deploy a VPN:

python3 -m virtualenv --python="$(command -v python3)" .env &&
  source .env/bin/activate &&
  python3 -m pip install -U pip virtualenv &&
  python3 -m pip install -r requirements.txt

This creates friction for our primary use case: security-conscious users who want a personal VPN but aren't necessarily Python developers.

Goals

1. Minimize prerequisites - Reduce the number of tools users need to install
2. Simplify commands - Make the setup process as simple as possible
3. Reduce confusion - Avoid concepts like virtual environments if possible
4. Maintain compatibility - Keep working for power users and developers

Proposed Solutions

Option 1: Single-file executable (Recommended for investigation)

• Use PyInstaller or similar to create platform-specific executables
• Users download one file and run it - no Python installation needed
• Pros: Zero Python knowledge required
• Cons: Larger download, platform-specific builds needed

Option 2: System packages approach

• Use system Python and install directly (with --user flag)
• Simplified one-liner: python3 -m pip install --user -r requirements.txt
• Pros: Simple, works with system Python
• Cons: Potential conflicts, requires Python pre-installed

Option 3: Modern tooling with fallback

• Document uv as the fast, simple option: uv pip install -r requirements.txt
• Keep traditional virtualenv as fallback
• Pros: Best of both worlds
• Cons: Still requires tool installation

Option 4: Docker/container approach

• Provide pre-built container with all dependencies
• One command: docker run -it algo:latest
• Pros: Completely isolated, reproducible
• Cons: Requires Docker, may be overkill

Discussion Points

1. What's our primary user persona? How technical are they?
2. Are we willing to maintain platform-specific builds?
3. Should we optimize for the Cloud Shell use case (where Python is pre-installed)?
4. Is adding Docker as a dependency worse than Python for our users?

Next Steps

1. Survey users about their comfort level with current setup
2. Prototype the most promising approach
3. Test with non-technical users
4. Update documentation to emphasize the simplest path

The goal is to get users from zero to deployed VPN with minimal friction and minimal required knowledge about Python packaging.

[dguido]

I just realized that since we require Python 3.11 for Ansible v11, Algo no longer works on the MacOS system Python (v3.9). We definitely want to rewrite the installation instructions now.

[dguido]

Recommendation: Use uv as the Primary Installation Method

After analyzing the current Python version requirements and installation friction, I believe Option 3 (Modern tooling with uv) is the best path forward. Here's why:

Current Problem

• Algo requires Python 3.10+ (due to ansible-core 2.16 dropping Python 3.9 support)
• macOS system Python is 3.9, creating an immediate barrier
• Current installation requires 4-5 commands and virtual environment knowledge

Why uv Solves This Perfectly

1. Automatic Python Management

# uv can install the required Python version automatically
uv python install 3.11
uv run ansible-playbook main.yml

2. Zero Prerequisites

• uv's installer downloads pre-compiled binaries (no Rust compilation needed)
• Works on all platforms (macOS Intel/ARM, Linux, Windows)
• Single curl command installs everything needed

3. Dramatic Simplification

Before (current):

python3 -m virtualenv --python="$(command -v python3)" .env &&
  source .env/bin/activate &&
  python3 -m pip install -U pip virtualenv &&
  python3 -m pip install -r requirements.txt

After (with uv):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv run ansible-playbook main.yml

4. Handles the Core Issues

• ✅ Minimal prerequisites (just curl)
• ✅ Simplest possible commands
• ✅ Eliminates virtual environment confusion
• ✅ Automatically handles Python version requirements
• ✅ Works for both non-developers and power users

Implementation Plan

1. Update installation documentation to recommend uv as primary method
2. Keep traditional virtualenv as fallback for advanced users
3. Add detection script that suggests the best installation path
4. Optimize for Cloud Shell as zero-setup alternative

This approach directly addresses the "macOS Python 3.9 vs Algo's Python 3.10+ requirement" problem while providing the simplest possible user experience for non-developers.

The key insight: instead of lowering our Python requirements (which would require downgrading Ansible), we make Python version management invisible to users.