Python Package Support - Deployment Checklist

Production deployment guide for Python package support with verification procedures and rollback instructions

Last Updated: February 19, 2026

Pre-Deployment
Post-Deployment
Rollback Procedure
Production Readiness
Monitoring

Pre-Deployment

Dependencies Installed

Check that all required dependencies are installed:

pip-audit 2.17+ installed

pip-audit --version
# Expected: pip-audit 2.17.0 or higher

safety 3.0+ installed (optional but recommended)

safety --version
# Expected: safety 3.0.0 or higher

pipdeptree 2.13+ installed

pipdeptree --version
# Expected: pipdeptree 2.13.0 or higher

packaging 21.0+ installed

python -c "import packaging; print(packaging.__version__)"
# Expected: 21.0 or higher

Installation Command:

pip install -r backend/requirements.txt

Docker Available

Verify Docker is installed and running:

Docker daemon running

docker version
# Expected: Docker version information

Docker SDK for Python installed

pip show docker
# Expected: Version: 7.0.0 or higher

Can pull base image

docker pull python:3.11-slim
# Expected: Successfully pulled image

Can build images

docker build -t test-build -f - <<EOF
FROM python:3.11-slim
RUN python --version
EOF
# Expected: Successfully built image

Database Migrations

Verify database schema is up to date:

Alembic migration applied

cd backend
alembic upgrade head
# Expected: "Running upgrade... -> XXXX"

package_registry table exists

python -c "from core.models import PackageRegistry; print('Table exists')"
# Expected: No error

Indexes created (name, version)

python <<EOF
from core.database import SessionLocal
from core.models import PackageRegistry
from sqlalchemy import inspect

db = SessionLocal()
inspector = inspect(PackageRegistry.__table__)
indexes = [idx.name for idx in inspector.indexes]
print("Indexes:", indexes)
# Expected: ['ix_package_registry_name', 'ix_package_registry_version']
EOF

Environment Variables

Verify environment variables are configured:

SAFETY_API_KEY set (optional)

echo $SAFETY_API_KEY
# Expected: API key string or empty (optional)

PACKAGE_CACHE_TTL configured (default: 60)

echo $PACKAGE_CACHE_TTL
# Expected: 60 (or custom value)

PACKAGE_CACHE_MAX_SIZE configured (default: 1000)

echo $PACKAGE_CACHE_MAX_SIZE
# Expected: 1000 (or custom value)

Configuration File: .env

# Python Package Scanning (Phase 35)
SAFETY_API_KEY=your_api_key_here  # Optional
PACKAGE_CACHE_TTL=60
PACKAGE_CACHE_MAX_SIZE=1000

Security Tests

Run security tests before deployment:

All security tests passing

PYTHONPATH=/Users/rushiparikh/projects/atom/backend pytest backend/tests/test_package_security.py -v
# Expected: 34 passed in 1.7 seconds

Container escape tests passing

pytest backend/tests/test_package_security.py::TestContainerEscape -v
# Expected: 4 passed

Resource exhaustion tests passing

pytest backend/tests/test_package_security.py::TestResourceExhaustion -v
# Expected: 4 passed

Malicious pattern tests passing

pytest backend/tests/test_package_security.py::TestMaliciousPatternDetection -v
# Expected: 8 passed

Integration Tests

Run integration tests:

All integration tests passing

PYTHONPATH=/Users/rushiparikh/projects/atom/backend pytest backend/tests/test_package_skill_integration.py -v
# Expected: 11+ passed

Package installation working

pytest backend/tests/test_package_skill_integration.py::test_install_packages_for_skill -v
# Expected: PASSED

Package execution working

pytest backend/tests/test_package_skill_integration.py::test_execute_skill_with_packages -v
# Expected: PASSED

Governance enforcement working

pytest backend/tests/test_package_skill_integration.py::test_governance_enforcement -v
# Expected: PASSED

Code Quality

Run code quality checks:

MyPy type checking passing

cd backend
mypy core/package_governance_service.py
# Expected: Success: no issues found

No linting errors

pylint core/package_governance_service.py
# Expected: No errors (warnings acceptable)

Code coverage acceptable

pytest backend/tests/test_package_security.py --cov=core/skill_sandbox --cov=core/package_governance_service --cov-report=term-missing
# Expected: Coverage >80% for critical paths

Post-Deployment

API Endpoints

Verify all package management endpoints are accessible:

GET /api/packages/check returns 200

curl "http://localhost:8000/api/packages/check?agent_id=test-agent&package_name=numpy&version=1.21.0"
# Expected: {"allowed": false, "maturity_required": "INTERN", "reason": "..."}

POST /api/packages/install returns 200

curl -X POST http://localhost:8000/api/packages/install \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "test-agent",
    "skill_id": "test-skill",
    "requirements": ["requests==2.28.0"],
    "scan_for_vulnerabilities": true
  }'
# Expected: {"success": true, "image_tag": "atom-skill:test-skill-v1", ...}

POST /api/packages/execute returns 200

curl -X POST http://localhost:8000/api/packages/execute \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "test-agent",
    "skill_id": "test-skill",
    "code": "import requests; print(requests.__version__)"
  }'
# Expected: {"success": true, "output": "2.28.0"}

DELETE /api/packages/{skill_id} returns 200

curl -X DELETE "http://localhost:8000/api/packages/test-skill?agent_id=test-agent"
# Expected: {"success": true, "message": "Image removed successfully"}

GET /api/packages/audit returns 200

curl http://localhost:8000/api/packages/audit
# Expected: {"operations": [...], "count": N}

Permission Checks

Verify governance rules are enforced:

STUDENT agents blocked from packages

# Create STUDENT agent
curl -X POST http://localhost:8000/api/agents \
  -d '{"name": "Test Student", "maturity": "STUDENT"}'

# Check permission
curl "http://localhost:8000/api/packages/check?agent_id=<student-id>&package_name=numpy&version=1.21.0"
# Expected: {"allowed": false, "maturity_required": "INTERN", "reason": "STUDENT agents cannot execute Python packages"}

INTERN agents require approval

# Create INTERN agent
curl -X POST http://localhost:8000/api/agents \
  -d '{"name": "Test Intern", "maturity": "INTERN"}'

# Check permission (unapproved package)
curl "http://localhost:8000/api/packages/check?agent_id=<intern-id>&package_name=unknown-pkg&version=1.0.0"
# Expected: {"allowed": false, "reason": "Package not approved"}

SUPERVISED agents allowed with approved packages

# Approve package
curl -X POST http://localhost:8000/api/packages/approve \
  -d '{"package_name": "requests", "version": "2.28.0", "min_maturity": "SUPERVISED"}'

# Create SUPERVISED agent
curl -X POST http://localhost:8000/api/agents \
  -d '{"name": "Test Supervised", "maturity": "SUPERVISED"}'

# Check permission
curl "http://localhost:8000/api/packages/check?agent_id=<supervised-id>&package_name=requests&version=2.28.0"
# Expected: {"allowed": true, "maturity_required": "SUPERVISED"}

AUTONOMOUS agents allowed with approved packages

# Approve package for AUTONOMOUS
curl -X POST http://localhost:8000/api/packages/approve \
  -d '{"package_name": "numpy", "version": "1.21.0", "min_maturity": "AUTONOMOUS"}'

# Create AUTONOMOUS agent
curl -X POST http://localhost:8000/api/agents \
  -d '{"name": "Test Autonomous", "maturity": "AUTONOMOUS"}'

# Check permission
curl "http://localhost:8000/api/packages/check?agent_id=<autonomous-id>&package_name=numpy&version=1.21.0"
# Expected: {"allowed": true, "maturity_required": "AUTONOMOUS"}

Vulnerability Scanning

Verify vulnerability scanning is operational:

pip-audit runs without errors

pip-audit --version
# Expected: No errors

Safety check runs (if API key provided)

if [ -n "$SAFETY_API_KEY" ]; then
  safety check --key $SAFETY_API_KEY
  # Expected: No errors
fi

Vulnerable packages blocked

# Attempt to install vulnerable package
curl -X POST http://localhost:8000/api/packages/install \
  -d '{
    "agent_id": "test-agent",
    "skill_id": "test-skill",
    "requirements": ["numpy==1.21.0"],
    "scan_for_vulnerabilities": true
  }'
# If vulnerable: {"success": false, "error": "Vulnerabilities detected", ...}

Scan results logged

curl http://localhost:8000/api/packages/audit?agent_id=test-agent
# Expected: Audit trail includes vulnerability scan results

Container Security

Verify Docker security constraints are enforced:

Network isolation enforced

# Inspect created container
docker inspect <container_id> | grep NetworkDisabled
# Expected: "NetworkDisabled": true

Read-only filesystem enforced

docker inspect <container_id> | grep ReadonlyRootfs
# Expected: "ReadonlyRootfs": true

No privileged mode

docker inspect <container_id> | grep Privileged
# Expected: "Privileged": false

No Docker socket mount

docker inspect <container_id> | grep -i "/var/run/docker.sock"
# Expected: (empty - not mounted)

Resource limits enforced

docker inspect <container_id> | jq '.HostConfig.Memory'
# Expected: 268435456 (256 MB)

docker inspect <container_id> | jq '.HostConfig.NanoCpus'
# Expected: 500000000 (0.5 cores)

Performance

Verify performance meets targets:

Governance cache hit rate >90%

# Check cache statistics (requires monitoring integration)
curl http://localhost:8000/health/metrics | grep governance_cache_hit_rate
# Expected: >0.90

Permission checks <1ms (P99)

# Run performance test
python <<EOF
import time
import requests

latencies = []
for _ in range(1000):
    start = time.time()
    requests.get("http://localhost:8000/api/packages/check?agent_id=test-agent&package_name=numpy&version=1.21.0")
    latencies.append((time.time() - start) * 1000)

latencies.sort()
p99 = latencies[int(len(latencies) * 0.99)]
print(f"P99 latency: {p99:.2f}ms")
# Expected: <1ms
EOF

Image build time <5min (typical packages)

# Time image build
time curl -X POST http://localhost:8000/api/packages/install \
  -d '{
    "agent_id": "test-agent",
    "skill_id": "test-skill",
    "requirements": ["pandas==1.3.0", "numpy==1.21.0"]
  }'
# Expected: <5min

Execution overhead <500ms

# Time execution (including container startup)
time curl -X POST http://localhost:8000/api/packages/execute \
  -d '{
    "agent_id": "test-agent",
    "skill_id": "test-skill",
    "code": "print('hello')"
  }'
# Expected: <500ms

Monitoring

Verify monitoring and logging:

Package operations logged (audit trail)

curl http://localhost:8000/api/packages/audit | jq '.operations | length'
# Expected: >0 (operations logged)

Vulnerability scans logged

curl http://localhost:8000/api/packages/audit | jq '.operations[] | .scan_results'
# Expected: Scan results in audit trail

Permission denials logged

# Attempt blocked operation
curl "http://localhost:8000/api/packages/check?agent_id=student-agent&package_name=numpy&version=1.21.0"

# Check logs
tail -f logs/atom.log | grep "Permission denied"
# Expected: Permission denial logged

Image build failures logged

# Attempt invalid install
curl -X POST http://localhost:8000/api/packages/install \
  -d '{"requirements": ["invalid-package==1.0.0"]}'

# Check logs
tail -f logs/atom.log | grep "Image build failed"
# Expected: Build failure logged

Rollback Procedure

If critical issues are detected after deployment, follow this rollback procedure.

Step 1: Disable Package Features

Disable package support without full rollback:

# Set emergency bypass
export EMERGENCY_GOVERNANCE_BYPASS=false  # Ensure bypass is OFF
export PYTHON_PACKAGES_ENABLED=false  # Add to .env if not present

# Restart services
systemctl restart atom-api  # Linux
# or
docker-compose restart api  # Docker

Step 2: Revert Database Migration

If database schema changes need to be reverted:

cd backend

# Check current migration
alembic current

# Revert one migration
alembic downgrade -1

# Verify rollback
alembic current
# Expected: Previous migration version

Warning: Downgrading may lose data added in the new migration.

Step 3: Remove API Routes

Remove package management endpoints from API router:

# backend/api/package_routes.py
# Comment out or delete router registration

# backend/main.py
# Remove: from api.package_routes import router as package_router
# Remove: app.include_router(package_router, prefix="/api/packages")

Step 4: Restart Services

# Restart API server
systemctl restart atom-api

# Verify endpoints removed
curl http://localhost:8000/api/packages/check
# Expected: 404 Not Found

Step 5: Verify System Stable

# Health checks
curl http://localhost:8000/health/live
# Expected: {"status": "alive"}

curl http://localhost:8000/health/ready
# Expected: {"status": "ready"}

# Test other endpoints still working
curl http://localhost:8000/api/agents
# Expected: Agent list returned

Step 6: Notify Users

Notify users of rollback:

Post on status page
Send email notification
Update changelog
Document rollback reason

Rollback Verification Checklist

Package endpoints removed (404 on /api/packages/*)
Database schema reverted (alembic current shows previous version)
No package-related errors in logs
Health checks passing
Other API endpoints working
Users notified

Production Readiness

Pre-Launch Checklist

Before launching to production:

All pre-deployment checks passed (see above)
All post-deployment checks passed (see above)
Security tests passed (test_package_security.py: 34/34)
Integration tests passed (test_package_skill_integration.py: 11+/14)
Documentation complete
- PYTHON_PACKAGES.md exists (>300 lines)
- PACKAGE_GOVERNANCE.md exists (>200 lines)
- PACKAGE_SECURITY.md exists (>250 lines)
- PYTHON_PACKAGES_DEPLOYMENT.md exists (this file)

Runbook Ready

Team Training

Security Validation

Performance Validation

Backup and Recovery

Final Sign-Off

Engineering lead approval
Security team approval
Operations team approval
Product owner approval

Monitoring

Key Metrics

Monitor these metrics in production:

Governance Cache:

Cache hit rate (target: >90%)
Cache latency P50, P99 (target: <1ms)
Cache size, evictions

Package Operations:

Install success rate (target: >95%)
Install duration (target: <5min)
Execution success rate (target: >90%)
Execution duration (target: <500ms overhead)

Security:

Vulnerability detection count
Permission denial count
Malicious pattern detection count
Blocked container escape attempts

Container Resources:

Memory usage per container
CPU usage per container
Container count (active, total)
Image registry size

Alerting

Configure alerts for:

Critical Alerts:

Container escape attempt detected
Malicious package approved and executed
Vulnerability scan failure
Database migration failure

Warning Alerts:

Cache hit rate <80%
Permission check latency P99 >5ms
Install success rate <90%
Execution timeout rate >5%

Info Alerts:

New package approved
Package banned
Agent graduated (maturity change)

Logging

Key log entries to monitor:

# Permission checks
tail -f logs/atom.log | grep "Package permission"

# Container operations
tail -f logs/atom.log | grep "Container"

# Security events
tail -f logs/atom.log | grep -E "Vulnerability|Malicious|Blocked"

# Errors
tail -f logs/atom.log | grep "ERROR"

Health Checks

Continuous health monitoring:

# Liveness probe (every 10s)
watch -n 10 'curl -s http://localhost:8000/health/live'

# Readiness probe (every 30s)
watch -n 30 'curl -s http://localhost:8000/health/ready'

# Metrics scrape (every 60s)
watch -n 60 'curl -s http://localhost:8000/health/metrics'

Uh oh!

FilesExpand file tree

python-packages.md

Latest commit

History

python-packages.md

File metadata and controls

Python Package Support - Deployment Checklist

Table of Contents

Pre-Deployment

Dependencies Installed

Docker Available

Database Migrations

Environment Variables

Security Tests

Integration Tests

Code Quality

Post-Deployment

API Endpoints

Permission Checks

Vulnerability Scanning

Container Security

Performance

Monitoring

Rollback Procedure

Step 1: Disable Package Features

Step 2: Revert Database Migration

Step 3: Remove API Routes

Step 4: Restart Services

Step 5: Verify System Stable

Step 6: Notify Users

Rollback Verification Checklist

Production Readiness

Pre-Launch Checklist

Runbook Ready

Team Training

Security Validation

Performance Validation

Backup and Recovery

Final Sign-Off

Monitoring

Key Metrics

Alerting

Logging

Health Checks

See Also