Portainer Deployment Architecture

Why Portainer is Recommended

Portainer-based deployment is the preferred method for Chatty AI for several key reasons:

Centralized Management

• Single Control Plane: Manage multiple Chatty AI deployments from one Portainer Server
• GUI-Based Operations: No need for command-line access to deployment servers
• Visual Stack Management: See all containers, volumes, and networks at a glance
• Easy Updates: Update images and configurations through the Portainer interface

Remote Deployment Support

• Edge Agent Architecture: Manage deployments behind firewalls and in private networks
• No Inbound Connections: Edge Agent initiates outbound connections to Portainer Server
• VPN-Friendly: Works seamlessly with VPN-protected environments
• Secure Communication: Encrypted tunnel between Edge Agent and Portainer Server

Simplified Lifecycle Management

• One-Click Updates: Update stack versions without manual image pulling
• Easy Rollback: Revert to previous stack versions if needed
• Environment Management: Update environment variables through GUI
• Stack Templates: Reuse configurations across multiple deployments

Operational Benefits

• Reduced Complexity: Less manual intervention required
• Consistency: Standardized deployment process across environments
• Audit Trail: Track who made changes and when
• Health Monitoring: Visual container health status

Portainer Architecture Overview

IMPORTANT: Portainer Server is managed by the VENDOR, not the customer. Customers do NOT need Portainer access.

Components

┌─────────────────────────────────────────────────────┐
│  Portainer Server (VENDOR-MANAGED)                  │
│  - Vendor controls deployment                       │
│  - Vendor manages stack updates                     │
│  - Customer has NO access to Portainer              │
└────────────────────┬────────────────────────────────┘
                     │
                     │ HTTPS + WebSocket (Outbound from Customer)
                     │ Port 443 + 8000
                     │
┌────────────────────▼────────────────────────────────┐
│  Customer Environment                               │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │  Portainer Edge Agent                      │    │
│  │  - Connects to VENDOR Portainer Server     │    │
│  │  - Receives deployment commands from vendor│    │
│  │  - Reports status to vendor                │    │
│  └────────────────┬───────────────────────────┘    │
│                   │                                 │
│                   ▼                                 │
│  ┌────────────────────────────────────────────┐    │
│  │  Docker Engine                             │    │
│  │  - Runs Chatty AI stack                    │    │
│  │  - Managed by vendor via Edge Agent        │    │
│  └────────────────────────────────────────────┘    │
│                                                      │
│  ┌────────────────────────────────────────────┐    │
│  │  Chatty AI Stack                           │    │
│  │  - nginx, chattyai, db, qdrant, n8n, etc.  │    │
│  └────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

Edge Agent Role

The Portainer Edge Agent is a lightweight container that:

1. Establishes Secure Connection: Creates encrypted tunnel to Portainer Server
2. Receives Commands: Gets stack deployment and update instructions
3. Executes Operations: Deploys, updates, and manages Docker stacks
4. Reports Status: Sends container health and metrics back to Portainer Server
5. Enables Remote Access: Allows Portainer Server to manage the environment

Key Characteristics

• Outbound Only: Agent initiates connection; no inbound ports required
• Lightweight: Minimal resource footprint
• Secure: TLS-encrypted communication
• Resilient: Automatically reconnects if connection drops

Deployment Workflow

Initial Setup

1. Portainer Server provides Edge Agent deployment command
2. Customer runs Edge Agent container on Docker host
3. Edge Agent connects to Portainer Server and registers
4. Portainer Server shows environment as available

Stack Deployment

1. Administrator creates or imports Chatty AI stack in Portainer
2. Environment Variables are configured through Portainer UI
3. Stack is deployed to Edge Agent environment
4. Edge Agent pulls images and starts containers
5. Status is reported back to Portainer Server

Updates

1. New Version is available in Portainer stack definition
2. Administrator updates image tags or environment variables
3. Portainer sends update command to Edge Agent
4. Edge Agent pulls new images and recreates containers
5. Health Status confirms successful update

Network Requirements

Outbound from Customer Environment

Edge Agent requires outbound access to vendor Portainer Server:

• Destination: Vendor Portainer Server URL (e.g., portainer.chatty-ai.ai)
• Port 443: HTTPS (API communication)
• Port 8000: WebSocket (tunnel for real-time management)
• Protocol: HTTPS + WebSocket
• Initiated By: Edge Agent (customer side)
• Frequency: Persistent connection

Firewall Rules Required:

Source: Customer Docker host
Destination: portainer.chatty-ai.ai (vendor)
Ports: 443/tcp, 8000/tcp
Direction: Outbound only

No Inbound Requirements

• Edge Agent does not require any inbound firewall rules
• All communication is initiated from customer environment
• Customer does NOT expose any management ports
• Ideal for environments with strict inbound restrictions

When to Use Portainer Deployment

✅ Use Portainer when:

• Vendor manages deployment (recommended for most customers)
• Deployments are in private networks or behind VPNs
• Customer wants vendor to handle updates and management
• Customer can allow outbound HTTPS + WebSocket to vendor
• Multiple environments need centralized vendor oversight

❌ Consider Docker Compose when:

• Customer requires full control without vendor access
• Customer cannot allow outbound connections to vendor Portainer
• Organizational policies prohibit external management
• Customer has strong Docker expertise and prefers manual control

Security Considerations

Vendor-Managed Portainer

• Vendor controls Portainer Server (customer has no access)
• Vendor secures Portainer with strong authentication and RBAC
• Vendor maintains audit logs of all deployment activities
• Customer trusts vendor to manage deployments securely

Edge Agent Security

• Edge Agent uses TLS for all communication (ports 443 + 8000)
• Agent tokens are provided by vendor during setup
• Agent tokens should be treated as secrets by customer
• Only vendor can rotate agent tokens
• Customer monitors Edge Agent connection status

Customer Network Security

• Customer must allow outbound to vendor Portainer Server:
  • Port 443 (HTTPS)
  • Port 8000 (WebSocket)
• Customer firewall should whitelist vendor Portainer URL
• No inbound ports required on customer side
• Consider VPN for additional security layer (optional)
• Monitor outbound connections for anomalies

Advantages Over Manual Deployment

Feature	Portainer	Docker Compose
Remote Management	✅ Yes	❌ Requires direct access
GUI Interface	✅ Yes	❌ Command-line only
Easy Updates	✅ One-click	⚠️ Manual process
Rollback	✅ Simple	⚠️ Manual
Multi-Environment	✅ Centralized	⚠️ Per-environment
Audit Trail	✅ Built-in	❌ Manual logging
Learning Curve	⚠️ Moderate	✅ Minimal (if familiar with Docker)
Dependencies	⚠️ Requires Portainer	✅ Docker only

Best Practices

1. Use Portainer Business/Enterprise for production deployments with support
2. Implement RBAC to control who can deploy and update stacks
3. Monitor Edge Agent connection status regularly
4. Test Updates in staging environment before production
5. Document Portainer Server URL and access procedures
6. Backup Portainer Server configuration and stack definitions
7. Rotate Edge Agent tokens periodically
8. Review audit logs for deployment changes