Guía de Instalación

Esta guía te ayudará a instalar y configurar Peeka en diferentes entornos.

Tabla de Contenidos

1. Requisitos del Sistema
   1. Requisitos Básicos
   2. Comparación de Versiones de Python
2. Métodos de Instalación
   1. Instalación con pip (recomendado)
      1. Versión básica (solo CLI)
      2. Versión completa (incluye TUI)
   2. Instalación con uv
   3. Instalación desde código fuente
3. Configuración Adicional para Python < 3.14
   1. Debian/Ubuntu
   2. RHEL/CentOS/Fedora
   3. macOS
4. Configuración de Permisos
   1. Sistema Linux
      1. Relajar temporalmente la restricción ptrace (solo para pruebas)
      2. Configuración permanente (recomendado para producción)
      3. Sistema SELinux (Fedora/RHEL)
   2. Contenedores Docker
5. Verificar la Instalación
   1. Verificar versión
   2. Ejecutar prueba
   3. Verificar dependencias
6. Preguntas Frecuentes
   1. Adjunte falló: permisos insuficientes
   2. Linux, Python < 3.14: no se encuentran los símbolos de depuración
   3. Versión de GDB demasiado antigua
   4. macOS: LLDB no disponible o sin permiso
7. Siguientes Pasos
8. Obtener Ayuda

---

Requisitos del Sistema

Requisitos Básicos

• Versión de Python: Python 3.8.1 o superior
• Sistema Operativo: Linux (recomendado), macOS
• Permisos: Se necesitan permisos para adjuntarse al proceso objetivo (mismo UID o CAP_SYS_PTRACE)

Comparación de Versiones de Python

Versión de Python	Mecanismo de Adjunte	Requisitos Adicionales
3.14+	PEP 768 sys.remote_exec	Ninguno
3.8.1-3.13	Linux: GDB + ptrace; macOS: LLDB + dlopen	Linux: GDB 7.3+, python3-dbg, CAP_SYS_PTRACE; macOS: Xcode Command Line Tools

---

Métodos de Instalación

Instalación con pip (recomendado)

Versión básica (solo CLI)

pip install peeka

Versión completa (incluye TUI)

pip install peeka[tui]

Instalación con uv

# Versión básica
uv pip install peeka

# Versión completa (incluye TUI)
uv pip install "peeka[tui]"

# Entorno de desarrollo (desde código fuente)
uv sync --dev

Instalación desde código fuente

# Clonar el repositorio
git clone https://github.com/peeka-project/peeka.git
cd peeka

# Instalar (versión básica)
uv pip install -e .

# Instalar (incluye TUI)
uv pip install -e ".[tui]"

# Entorno de desarrollo (dependencias completas)
uv sync --dev

---

Configuración Adicional para Python < 3.14

Para Python 3.8.1-3.13, Linux necesita GDB y símbolos de depuración de Python; macOS usa LLDB y necesita Xcode Command Line Tools.

Debian/Ubuntu

sudo apt-get update
sudo apt-get install gdb python3-dbg

RHEL/CentOS/Fedora

sudo yum install gdb python3-debuginfo

macOS

xcode-select --install

---

Configuración de Permisos

Sistema Linux

Relajar temporalmente la restricción ptrace (solo para pruebas)

echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Configuración permanente (recomendado para producción)

Edita /etc/sysctl.d/10-ptrace.conf:

kernel.yama.ptrace_scope = 1

Luego aplica la configuración:

sudo sysctl -p /etc/sysctl.d/10-ptrace.conf

Sistema SELinux (Fedora/RHEL)

# Verificar estado de SELinux
getenforce

# Permitir ptrace temporalmente
sudo setsebool -P deny_ptrace off

# O crear una política SELinux para procesos específicos

Contenedores Docker

Agrega el parámetro --cap-add=SYS_PTRACE al ejecutar tu contenedor Docker:

docker run --cap-add=SYS_PTRACE your-image

O configúralo en docker-compose.yml:

services:
  app:
    image: your-image
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp=unconfined

---

Verificar la Instalación

Verificar versión

peeka-cli --version
# peeka-cli 0.1.10

Ejecutar prueba

# Iniciar aplicación de demostración
python -m peeka.examples.demo --mode loop

# En otra terminal prueba adjuntar
peeka-cli attach <pid>

Verificar dependencias

# Verificar versión de Python
python --version

# Verificar GDB (Linux, Python < 3.14)
gdb --version

# Verificar LLDB (macOS, Python < 3.14)
lldb --version

# Verificar símbolos de depuración de Python (Linux, Python < 3.14)
python -c "import sys; print(hasattr(sys, 'gettotalrefcount'))"

---

Preguntas Frecuentes

Adjunte falló: permisos insuficientes

Mensaje de error:

Error: Operation not permitted

Solución:

1. Asegúrate de tener el mismo UID que el proceso objetivo o usa sudo
2. Verifica la configuración de ptrace_scope
3. Para Docker, asegúrate de haber agregado CAP_SYS_PTRACE

Linux, Python < 3.14: no se encuentran los símbolos de depuración

Mensaje de error:

Error: Python debugging symbols not found

Solución:

# Debian/Ubuntu
sudo apt-get install python3-dbg

# RHEL/CentOS
sudo yum install python3-debuginfo

Versión de GDB demasiado antigua

Mensaje de error:

Error: GDB version 7.3+ required

Solución:

# Actualizar GDB
sudo apt-get update
sudo apt-get install --only-upgrade gdb

# O compila la última versión desde código fuente

macOS: LLDB no disponible o sin permiso

Mensaje de error:

Error: LLDB not found
Error: LLDB attach failed: permission denied

Solución: Instala Xcode Command Line Tools:

xcode-select --install

---

Siguientes Pasos

Después de completar la instalación, puedes:

• Inicio Rápido - Aprender el uso básico
• Referencia de Comandos - Ver todos los comandos disponibles
• Ejemplos y Tutoriales - Escenarios prácticos de aplicación

---

Obtener Ayuda

Si encuentras problemas durante la instalación:

1. Consulta Resolución de Problemas
2. Pregunta en GitHub Issues