Intelligent Deployment

Every portoser deploy runs through a four-stage loop that observes the target host, classifies any failures it sees against known patterns, applies the matching fix, and saves new fixes back to the knowledge base for next time. The loop is on by default — you opt out per-deploy with --no-auto-heal.

What runs, where it lives

The loop is the differentiator. Most orchestrators stop at "deploy failed" — Portoser tries to figure out why and what to do about it from a growing library of fixes.

How the loop runs

1. Observe

Before deploying, Portoser observes the environment:

✓ Checking SSH connectivity
✓ Verifying disk space
✓ Checking if service is already running
✓ Inspecting port availability
✓ Verifying Docker daemon (if needed)
✓ Checking dependencies health

Example Output:

[OBSERVE] Connecting to m1 (192.168.0.245)...
[OBSERVE] SSH connection successful
[OBSERVE] Disk space: 45GB available
[OBSERVE] Port 8080: Available
[OBSERVE] Docker daemon: Running
[OBSERVE] Dependencies: All healthy

2. Analyze

If issues are detected, Portoser analyzes the root cause:

✓ Port conflict detected
✓ Analyzing process using port 8080
✓ Checking if it's a stale process
✓ Reviewing process ownership
✓ Determining safe resolution

Example Output:

[DIAGNOSE] Port 8080 is in use
[DIAGNOSE] Process: node (PID 1234)
[DIAGNOSE] Owner: admin
[DIAGNOSE] Status: Stale process (no parent)
[DIAGNOSE] Resolution: Safe to terminate

3. Solve

Portoser automatically applies proven solutions:

✓ Stopping stale process on port 8080
✓ Cleaning up PID file
✓ Verifying port is now available
✓ Proceeding with deployment

Example Output:

[SOLVE] Terminating stale process (PID 1234)
[SOLVE] Removing PID file: /var/run/myapp.pid
[SOLVE] Port 8080 now available
[SOLVE] Problem resolved - continuing deployment

4. Learn

Successful solutions are stored for future use:

✓ Recording solution in knowledge base
✓ Updating playbook: port_conflict_resolution
✓ Solution available for future deployments

Example Output:

[STANDARDIZE] Storing solution pattern
[STANDARDIZE] Pattern: stale_process_on_port
[STANDARDIZE] Success rate: 98% (45/46 deployments)
[STANDARDIZE] Knowledge base updated

Common Issues Resolved

1. Port Conflicts

Problem: Service can't start because port is already in use

Detection:

• Check if port is bound
• Identify process using port
• Determine if process is legitimate or stale

Solution:

• Terminate stale processes
• Update conflicting service configuration
• Assign new port if needed

Example:

# Deploy with intelligent mode
portoser deploy my-app --intelligent

# Output:
# [DIAGNOSE] Port 8080 conflict detected
# [SOLVE] Stopping stale process
# [DEPLOY] Service started successfully on port 8080

2. Stale PID Files

Problem: Service won't start due to leftover PID file from previous crash

Detection:

• Check for PID file existence
• Verify if process is actually running
• Determine if PID file is stale

Solution:

• Verify process is not running
• Remove stale PID file
• Proceed with startup

Example:

# Intelligent deployment handles this automatically
portoser deploy my-app --intelligent

# Output:
# [DIAGNOSE] Stale PID file detected: /var/run/myapp.pid
# [SOLVE] Removing stale PID file
# [DEPLOY] Service started successfully

3. Docker Daemon Not Running

Problem: Docker service deployment fails because Docker isn't running

Detection:

• Check Docker daemon status
• Verify Docker socket availability
• Test Docker command execution

Solution:

• Start Docker daemon
• Wait for Docker to be ready
• Verify Docker is accessible
• Proceed with deployment

Example:

portoser deploy my-docker-app --intelligent

# Output:
# [DIAGNOSE] Docker daemon not running
# [SOLVE] Starting Docker daemon
# [SOLVE] Waiting for Docker to be ready...
# [SOLVE] Docker is now running
# [DEPLOY] Starting Docker Compose deployment

4. Low Disk Space

Problem: Deployment fails due to insufficient disk space

Detection:

• Check available disk space
• Compare with deployment requirements
• Identify large temporary files

Solution:

• Clean Docker unused images/containers
• Remove old log files
• Clear temporary files
• Re-check available space

Example:

portoser deploy my-app --intelligent

# Output:
# [DIAGNOSE] Low disk space: 500MB available
# [SOLVE] Cleaning unused Docker images
# [SOLVE] Removing old logs (>30 days)
# [SOLVE] Freed 2.5GB
# [DEPLOY] Sufficient space now available

5. Dependency Health Failures

Problem: Service depends on unhealthy services

Detection:

• Check all service dependencies
• Test dependency health endpoints
• Identify which dependencies are unhealthy

Solution:

• Attempt to restart unhealthy dependencies
• Wait for dependencies to become healthy
• Retry health checks
• Proceed when all healthy

Example:

portoser deploy web-app --intelligent

# Output:
# [DIAGNOSE] Dependency 'postgres' is unhealthy
# [SOLVE] Restarting postgres service
# [SOLVE] Waiting for postgres to be healthy...
# [SOLVE] Postgres is now healthy
# [DEPLOY] All dependencies ready - deploying web-app

6. Permission Issues

Problem: Service files have incorrect permissions

Detection:

• Check file ownership
• Verify execute permissions
• Test write access for logs

Solution:

• Fix file ownership
• Set correct permissions
• Create necessary directories

Example:

portoser deploy my-app --intelligent

# Output:
# [DIAGNOSE] Permission denied: /opt/my-app/start.sh
# [SOLVE] Setting execute permission
# [SOLVE] Creating log directory with correct permissions
# [DEPLOY] Permissions corrected - starting service

7. Network Issues

Problem: Service can't connect to dependencies or external services

Detection:

• Test network connectivity
• Verify DNS resolution
• Check firewall rules

Solution:

• Wait for network to stabilize
• Update DNS cache
• Suggest firewall rule changes

Using Intelligent Deployment

Basic Usage

# Deploy with intelligent mode
portoser deploy my-app --intelligent

# Short form
portoser deploy my-app -i

Dry Run

See what issues would be detected without actually deploying:

portoser deploy my-app --intelligent --dry-run

Verbose Mode

See detailed diagnostics:

portoser deploy my-app --intelligent --verbose

Force Mode

Skip all checks and deploy anyway (not recommended):

portoser deploy my-app --force

Configuration

Enable by Default

Set intelligent mode as default in your environment:

export PORTOSER_INTELLIGENT_DEPLOY=true

Or in .env:

PORTOSER_INTELLIGENT_DEPLOY=true

Customize Problem Patterns

Add custom problem detection patterns in /lib/solve/patterns/:

# Create custom pattern
cat > lib/solve/patterns/custom_check.sh << 'EOF'
#!/bin/bash

detect_custom_issue() {
    local service=$1
    # Your detection logic
}

solve_custom_issue() {
    local service=$1
    # Your solution logic
}
EOF

Configure Retry Behavior

# In registry.yml
services:
  my-app:
    intelligent:
      max_retries: 3
      retry_delay: 5
      auto_fix: true

Knowledge Base

View learned solutions:

# List all solution patterns
portoser knowledge list

# View specific pattern
portoser knowledge show port_conflict_resolution

# View success rates
portoser knowledge stats

Example Output:

Solution Patterns (Last 30 Days)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Pattern                    Occurrences  Success Rate
──────────────────────────────────────────────────
port_conflict              23           95.6%
stale_pid_file             18           100%
docker_not_running         12           91.7%
low_disk_space             8            87.5%
dependency_unhealthy       15           93.3%
permission_issues          6            100%

Best Practices

1. Use Intelligent Deployment for Production

Always use intelligent deployment for critical services:

portoser deploy production-api --intelligent

2. Review Diagnostics

Check diagnostic output to understand what was fixed:

portoser deploy my-app --intelligent --verbose > deploy.log

3. Monitor Knowledge Base

Regularly review learned patterns:

# Weekly knowledge base review
portoser knowledge stats --period 7d

4. Contribute Patterns

Share successful patterns with your team:

# Export pattern
portoser knowledge export port_conflict_resolution > pattern.yml

# Import pattern on another machine
portoser knowledge import pattern.yml

5. Test in Staging First

Test intelligent deployment in staging:

# Deploy to staging with intelligent mode
portoser deploy my-app --intelligent --machine staging

# If successful, deploy to production
portoser deploy my-app --intelligent --machine production

Limitations

What Intelligent Deployment Can't Fix

1. Application Bugs: Code-level errors must be fixed by developers
2. Configuration Errors: Invalid configuration requires manual review
3. Hardware Failures: Physical issues need hardware intervention
4. Network Outages: External network problems can't be auto-fixed
5. Security Policies: Firewall/security rules require manual approval

When to Skip Intelligent Mode

• Quick Debugging: When you need fast feedback loops
• Custom Deployments: When you know exactly what needs to happen
• Testing Failure Scenarios: When you want deployment to fail

Troubleshooting

Intelligent Deployment Not Detecting Issues

# Enable verbose mode
portoser deploy my-app --intelligent --verbose

# Check pattern files
ls -la lib/solve/patterns/

# List recognized patterns and their playbooks
portoser learn playbooks

Solutions Not Being Applied

# Check permissions
ls -la lib/solve/

# Review logs
portoser logs --component intelligent-deploy

# Test pattern manually
bash lib/solve/patterns/port_conflict.sh

Knowledge Base Not Updating

# Knowledge base lives here — verify it's writable
ls -la ~/.portoser/knowledge/playbooks/

# Service-level insights — what's failed, what got auto-fixed
portoser learn insights my-app --json-output

Advanced Features

Custom Problem Detection

Create custom detection logic:

# Add to lib/diagnose/custom.sh
detect_custom_problem() {
    local service=$1
    # Your custom detection logic
    if [[ condition ]]; then
        echo "PROBLEM_DETECTED"
        return 1
    fi
    return 0
}

Solution Prioritization

Define solution priority:

services:
  my-app:
    intelligent:
      solution_priority:
        - restart_dependencies
        - clear_cache
        - rebuild_containers

Rollback on Failure

Automatically rollback if intelligent deployment fails:

portoser deploy my-app --intelligent --rollback-on-failure

Inspecting what the loop has learned

The knowledge base is exposed through portoser learn:

# Headline summary of what's been recorded
portoser learn summary

# Full stats — total playbooks, success counts, last-seen timestamps
portoser learn stats --json-output

# All playbooks with frequency counts
portoser learn playbooks

# View a specific playbook
portoser learn playbook PROBLEM_PORT_CONFLICT

# Per-service insights — what's failed, what's been auto-fixed
portoser learn insights requirements --json-output

Playbooks live in ~/.portoser/knowledge/playbooks/ as plain files. They're versioned outside Git so they can grow per-host without polluting the project.

Next Steps

• Health Monitoring — what monitoring does and doesn't do
• Deployment History — track every deploy, roll back any of them
• Troubleshooting — fingerprint-by-fingerprint guide