HashWarlock · August 1, 2025 07:54
diff --git a/deploy_to_phala_cloud.mdc b/deploy_to_phala_cloud.mdc
 ---
 alwaysApply: true
 ---

 # Phala Cloud TEE Deployment Guide

 ## Overview

 This guide covers the deployment of applications to Phala Cloud's Trusted Execution Environment (TEE) infrastructure using the official Phala Cloud CLI. Phala Cloud provides confidential computing capabilities through Confidential Virtual Machines (CVMs) that ensure secure execution with hardware-based attestation.

 ## Core Concepts

 ### TEE (Trusted Execution Environment)

 - **Purpose**: Provides hardware-based security guarantees for application execution
 - **Benefits**: Private key protection, remote attestation, secure computation
 - **Phala Implementation**: Uses confidential computing with cryptographic proof of secure execution

 ### CVM (Confidential Virtual Machine)

 - **Definition**: Phala Cloud's containerized TEE environment
 - **Features**: Isolated execution, attestation capabilities, secure networking
 - **Use Case**: Production deployment of security-critical applications

 ## Prerequisites

 ### System Requirements

 ```bash
 # Required tools
 node --version                  # Node.js for npx commands
 docker --version                # Docker Desktop must be running
 ```

 ### Environment Setup

 ```bash
 # Typical environment variables for applications
 # Add your application-specific variables as needed
 API_KEY=your_key
 DATABASE_URL=your_database_url

 # Optional platform integrations
 DISCORD_TOKEN=your_token
 SLACK_TOKEN=your_token
 ```

 ### Account Setup

 - **Phala Cloud Account**: Register through CLI or at [Phala Cloud Dashboard](https://cloud.phala.network)
 - **API Key**: Obtain from Phala Cloud Dashboard settings
 - **DockerHub Account**: Required for image hosting

 ## Phala CLI Commands

 ### Main Commands Available

 ```bash
 # View all available commands
 npx phala help
 ```

 **Available Commands:**

 - `auth` - Authenticate with Phala Cloud
 - `cvms` - Manage Phala Confidential Virtual Machines (CVMs)
 - `docker` - Login to Docker Hub and manage Docker images
 - `simulator` - TEE simulator commands
 - `demo` - Demo commands to launch a demo on Phala Cloud
 - `join` or `free` - Join Phala Cloud! Get an account and deploy a CVM for FREE
 - `nodes` - List and manage TEE nodes

 ## Deployment Workflow

 ### Step 1: Get Phala Cloud Account

 ```bash
 # Join Phala Cloud for free
 npx phala join
 # or
 npx phala free
 ```

 ### Step 2: Authentication Commands

 ```bash
 # Login with your API key
 npx phala auth login [api-key]

 # Check authentication status
 npx phala auth status

 # Logout if needed
 npx phala auth logout
 ```

 ### Step 3: Docker Management Commands

 ```bash
 # Login to Docker Hub
 npx phala docker login

 # Build Docker image
 npx phala docker build

 # Push to Docker Hub
 npx phala docker push

 # Generate Docker Compose file
 npx phala docker generate
 ```

 ### Step 4: CVM Management Commands

 #### Creating CVMs

 ```bash
 # Create a new CVM
 npx phala cvms create [options]

 # Available options:
 # -n, --name <n>              Name of the CVM
 # -c, --compose <compose>     Path to Docker Compose file
 # --vcpu <vcpu>              Number of vCPUs, default is 2
 # --memory <memory>          Memory in MB, default is 4096
 # --disk-size <diskSize>     Disk size in GB, default is 40
 # --teepod-id <teepodId>     TEEPod ID to use
 # --image <image>            Version of dstack image to use
 # -e, --env-file <envFile>   Path to environment file
 # --skip-env                 Skip environment variable prompt
 # --debug                    Enable debug mode

 # Example:
 npx phala cvms create -n my-app -c docker-compose.yaml -e .env
 ```

 #### Managing CVMs

 ```bash
 # List all CVMs
 npx phala cvms list
 # or
 npx phala cvms ls

 # Get details of a specific CVM
 npx phala cvms get [app-id]

 # Start a stopped CVM
 npx phala cvms start [app-id]

 # Stop a running CVM
 npx phala cvms stop [app-id]

 # Restart a CVM
 npx phala cvms restart [app-id]

 # Delete a CVM
 npx phala cvms delete [app-id]
 ```

 #### CVM Operations

 ```bash
 # Resize CVM resources
 npx phala cvms resize [app-id]
 # Options: --vcpu, --memory, --disk-size, --allow-restart, --yes

 # Upgrade a CVM to a new version
 npx phala cvms upgrade [app-id]

 # Create a replica of an existing CVM
 npx phala cvms replicate <cvm-id>

 # List available worker nodes
 npx phala cvms list-nodes
 ```

 ### Step 5: TEE Attestation

 ```bash
 # Get attestation information for a CVM
 npx phala cvms attestation [app-id]
 ```

 **Critical**: This step confirms your application is running in a genuine TEE environment with cryptographic proof.

 ## TEE Development and Testing

 ### TEE Simulator (Local Testing)

 ```bash
 # Start TEE simulator
 npx phala simulator start

 # Stop TEE simulator
 npx phala simulator stop
 ```

 ### Demo Applications

 ```bash
 # Launch demo applications
 npx phala demo
 ```

 ### Node Management

 ```bash
 # List all available worker nodes
 npx phala nodes list
 # or
 npx phala nodes ls
 ```

 ## Private Registry Support

 For private Docker images, set these environment variables in your docker-compose file:

 ### DockerHub

 - `DSTACK_DOCKER_USERNAME` - Your DockerHub username
 - `DSTACK_DOCKER_PASSWORD` - Your DockerHub password or access token
 - `DSTACK_DOCKER_REGISTRY` - Registry URL (optional, defaults to DockerHub)

 ### AWS ECR

 - `DSTACK_AWS_ACCESS_KEY_ID` - AWS access key
 - `DSTACK_AWS_SECRET_ACCESS_KEY` - AWS secret key
 - `DSTACK_AWS_REGION` - AWS region
 - `DSTACK_AWS_ECR_REGISTRY` - Full ECR registry URL

 ## Example Docker Compose Configuration

 ```yaml
 version: '3.8'
 services:
  app:
    image: your-registry/your-app:latest
    environment:
      - NODE_ENV=production
      - API_KEY=${API_KEY}
      - DATABASE_URL=${DATABASE_URL}
    ports:
      - "3000:3000"
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - app-network

 networks:
  app-network:
    driver: bridge
 ```

 ## Complete Example Workflow

 ```bash
 # 1. Create account and authenticate
 npx phala free
 npx phala auth login <your-api-key>
 npx phala auth status

 # 2. Prepare your application
 # - Create Dockerfile for your application
 # - Create docker-compose.yaml
 # - Prepare .env file with environment variables

 # 3. Build and deploy with Docker
 npx phala docker build
 npx phala docker push
 npx phala docker generate

 # 4. Create CVM
 npx phala cvms create -n my-app -c docker-compose.yaml -e .env

 # 5. Verify deployment
 npx phala cvms list
 npx phala cvms attestation
 ```

 ## Getting Help

 ```bash
 # General help
 npx phala help

 # Command-specific help
 npx phala <command> --help

 # Examples:
 npx phala auth --help
 npx phala cvms --help
 npx phala cvms create --help
 npx phala docker --help
 ```

 ## Common Issues and Troubleshooting

 ### Authentication Issues

 ```bash
 # Check current auth status
 npx phala auth status

 # Re-login if needed
 npx phala auth logout
 npx phala auth login <your-api-key>
 ```

 ### CVM Management Issues

 ```bash
 # Check CVM status
 npx phala cvms list
 npx phala cvms get <app-id>

 # Restart if needed
 npx phala cvms restart <app-id>

 # Check available nodes
 npx phala cvms list-nodes
 ```

 ### Docker Issues

 ```bash
 # Ensure Docker is running
 docker ps

 # Login to Docker Hub through Phala CLI
 npx phala docker login
 ```

 ### Resource Issues

 ```bash
 # Check CVM details for resource usage
 npx phala cvms get <app-id>

 # Resize if needed
 npx phala cvms resize <app-id> --vcpu 4 --memory 8192 --disk-size 80
 ```

 ## Security Best Practices

 ### Environment Configuration

 - **Private Keys**: Never expose in logs, environment files, or code
 - **API Keys**: Use secure environment variable injection via `-e` flag
 - **Attestation**: Always verify TEE attestation before handling sensitive operations
 - **Network Security**: Use HTTPS for all external communications

 ### Key Management

 - **Hardware Protection**: Leverage TEE's hardware-based key protection
 - **Secure Channels**: All external communications must use TLS
 - **Regular Verification**: Use `npx phala cvms attestation` to verify secure execution

 ### Docker Security

 ```yaml
 # Security-focused docker-compose.yaml
 services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=100m
    user: "1000:1000"  # Non-root user
 ```

 ## Application Types Suitable for TEE

 ### High Security Applications

 - **Cryptocurrency wallets and trading bots**
 - **Identity verification systems**
 - **Medical data processing**
 - **Financial calculation engines**
 - **AI inference with sensitive data**

 ### Benefits for Each Type

 - **Confidentiality**: Data processing in encrypted memory
 - **Integrity**: Cryptographic proof of execution environment
 - **Availability**: Distributed infrastructure with high uptime
 - **Compliance**: Meets regulatory requirements for data protection

 ## Resource Planning

 ### CVM Resource Guidelines

 - **Small Apps**: 1-2 vCPU, 2-4GB RAM, 20-40GB disk
 - **Medium Apps**: 2-4 vCPU, 4-8GB RAM, 40-80GB disk
 - **Large Apps**: 4+ vCPU, 8+ GB RAM, 80+ GB disk

 ### Cost Optimization

 - Start with minimal resources and scale up based on usage
 - Use `npx phala cvms resize` to adjust resources dynamically
 - Monitor application performance and resource utilization
 - Stop non-production CVMs when not in use

 ## References

 - [Phala Cloud Documentation](https://docs.phala.network/phala-cloud)
 - [Phala Cloud Dashboard](https://cloud.phala.network)
 - [Official Phala CLI](https://www.npmjs.com/package/phala)
 - [TEE Technology Overview](https://docs.phala.network/developers/dstack-guide)
 - [Confidential Computing Consortium](https://confidentialcomputing.io/)

 ---

 **Note**: The Phala CLI is automatically downloaded via npx if not already installed. All commands work with any containerized application that can run in a Docker environment.

 ---

 ## ⚠️ CRITICAL: Platform Architecture Requirements

 ### **Docker Architecture Compatibility for TEE Deployment**

 **Phala Cloud TEE infrastructure REQUIRES `linux/amd64` architecture.** Deploying images built for other architectures will result in deployment failures.

 #### **Why This Matters:**

 - TEE (Trusted Execution Environment) hardware is based on x86_64/amd64 processors
 - ARM-based images (`linux/arm64`) cannot run in TEE environments
 - Most deployment failures are caused by incorrect image architecture

 #### **Platform Detection & Solutions:**

 **✅ RECOMMENDED: Use Phala CLI (Automatic Platform Handling)**

 ```bash
 # Phala CLI automatically detects your platform and builds for linux/amd64
 npx phala docker build -i your-image -t your-tag

 # Example output showing automatic platform conversion:
 # "Detected platform: darwin/arm64, converting to linux/amd64 for TEE compatibility"
 ```

 **⚠️ MANUAL DOCKER COMMANDS: Must Specify Platform**

 ```bash
 # ❌ WRONG: Uses your local architecture (may be arm64 on Apple Silicon)
 docker build -t your-image:tag .

 # ✅ CORRECT: Forces linux/amd64 architecture for TEE compatibility  
 docker build --platform=linux/amd64 -t your-image:tag .

 # ✅ ALTERNATIVE: Use buildx for multi-platform builds
 docker buildx build --platform=linux/amd64 -t your-image:tag .
 ```

 #### **Platform Verification Commands:**

 ```bash
 # Check your system architecture
 uname -m                    # Shows: arm64 (Apple M1/M2) or x86_64 (Intel)
 docker version --format '{{.Server.Arch}}'

 # Verify image architecture before deploying
 docker image inspect your-image:tag --format '{{.Architecture}}'
 # Must show: amd64 (NOT arm64)
 ```

 #### **Platform Compatibility Matrix:**

 | Your System | Default Docker Build | TEE Compatible | Action Required |
 |-------------|---------------------|----------------|-----------------|
 | **Apple M1/M2 Mac** | `linux/arm64` | ❌ **FAILS** | Use `--platform=linux/amd64` |
 | **Intel Mac** | `linux/amd64` | ✅ Works | None |
 | **Linux x86_64** | `linux/amd64` | ✅ Works | None |
 | **Linux ARM64** | `linux/arm64` | ❌ **FAILS** | Use `--platform=linux/amd64` |
 | **Windows x64** | `linux/amd64` | ✅ Works | None |

 #### **Common Error Symptoms:**

 - CVM status shows "Failed", "Error", or "Stopped"
 - Container starts but immediately crashes
 - Application doesn't respond after deployment
 - Logs show "exec format error" or architecture mismatch

 #### **Quick Fix for Existing Images:**

 ```bash
 # If you already have an arm64 image, rebuild it:
 docker build --platform=linux/amd64 -t your-image:tag .
 docker push your-image:tag

 # Then upgrade your CVM:
 npx phala cvms upgrade your-app-id -c docker-compose.yaml -e .env
 ```

 #### **Best Practices:**

 1. **Always use `npx phala docker build`** - it handles platform automatically
 2. **If using Docker directly:** Always include `--platform=linux/amd64`  
 3. **Verify before pushing:** Check image architecture with `docker image inspect`
 4. **Update CI/CD:** Ensure build pipelines specify `--platform=linux/amd64`

 # Phala Cloud TEE Deployment Guide

 ## Overview

 This guide covers the deployment of applications to Phala Cloud's Trusted Execution Environment (TEE) infrastructure using the official Phala Cloud CLI. Phala Cloud provides confidential computing capabilities through Confidential Virtual Machines (CVMs) that ensure secure execution with hardware-based attestation.

 ## Core Concepts

 ### TEE (Trusted Execution Environment)

 - **Purpose**: Provides hardware-based security guarantees for application execution
 - **Benefits**: Private key protection, remote attestation, secure computation
 - **Phala Implementation**: Uses confidential computing with cryptographic proof of secure execution

 ### CVM (Confidential Virtual Machine)

 - **Definition**: Phala Cloud's containerized TEE environment
 - **Features**: Isolated execution, attestation capabilities, secure networking
 - **Use Case**: Production deployment of security-critical applications

 ## Prerequisites

 ### System Requirements

 ```bash
 # Required tools
 node --version                  # Node.js for npx commands
 docker --version                # Docker Desktop must be running
 ```

 ### Environment Setup

 ```bash
 # Typical environment variables for applications
 # Add your application-specific variables as needed
 API_KEY=your_key
 DATABASE_URL=your_database_url

 # Optional platform integrations
 DISCORD_TOKEN=your_token
 SLACK_TOKEN=your_token
 ```

 ### Account Setup

 - **Phala Cloud Account**: Register through CLI or at [Phala Cloud Dashboard](https://cloud.phala.network)
 - **API Key**: Obtain from Phala Cloud Dashboard settings
 - **DockerHub Account**: Required for image hosting

 ## Phala CLI Commands

 ### Main Commands Available

 ```bash
 # View all available commands
 npx phala help
 ```

 **Available Commands:**

 - `auth` - Authenticate with Phala Cloud
 - `cvms` - Manage Phala Confidential Virtual Machines (CVMs)
 - `docker` - Login to Docker Hub and manage Docker images
 - `simulator` - TEE simulator commands
 - `demo` - Demo commands to launch a demo on Phala Cloud
 - `join` or `free` - Join Phala Cloud! Get an account and deploy a CVM for FREE
 - `nodes` - List and manage TEE nodes

 ## Deployment Workflow

 ### Step 1: Get Phala Cloud Account

 ```bash
 # Join Phala Cloud for free
 npx phala join
 # or
 npx phala free
 ```

 ### Step 2: Authentication Commands

 ```bash
 # Login with your API key
 npx phala auth login [api-key]

 # Check authentication status
 npx phala auth status

 # Logout if needed
 npx phala auth logout
 ```

 ### Step 3: Docker Management Commands

 ```bash
 # Login to Docker Hub
 npx phala docker login

 # Build Docker image
 npx phala docker build

 # Push to Docker Hub
 npx phala docker push

 # Generate Docker Compose file
 npx phala docker generate
 ```

 ### Step 4: CVM Management Commands

 #### Creating CVMs

 ```bash
 # Create a new CVM
 npx phala cvms create [options]

 # Available options:
 # -n, --name <n>              Name of the CVM
 # -c, --compose <compose>     Path to Docker Compose file
 # --vcpu <vcpu>              Number of vCPUs, default is 2
 # --memory <memory>          Memory in MB, default is 4096
 # --disk-size <diskSize>     Disk size in GB, default is 40
 # --teepod-id <teepodId>     TEEPod ID to use
 # --image <image>            Version of dstack image to use
 # -e, --env-file <envFile>   Path to environment file
 # --skip-env                 Skip environment variable prompt
 # --debug                    Enable debug mode

 # Example:
 npx phala cvms create -n my-app -c docker-compose.yaml -e .env
 ```

 #### Managing CVMs

 ```bash
 # List all CVMs
 npx phala cvms list
 # or
 npx phala cvms ls

 # Get details of a specific CVM
 npx phala cvms get [app-id]

 # Start a stopped CVM
 npx phala cvms start [app-id]

 # Stop a running CVM
 npx phala cvms stop [app-id]

 # Restart a CVM
 npx phala cvms restart [app-id]

 # Delete a CVM
 npx phala cvms delete [app-id]
 ```

 #### CVM Operations

 ```bash
 # Resize CVM resources
 npx phala cvms resize [app-id]
 # Options: --vcpu, --memory, --disk-size, --allow-restart, --yes

 # Upgrade a CVM to a new version
 npx phala cvms upgrade [app-id]

 # Create a replica of an existing CVM
 npx phala cvms replicate <cvm-id>

 # List available worker nodes
 npx phala cvms list-nodes
 ```

 ### Step 5: TEE Attestation

 ```bash
 # Get attestation information for a CVM
 npx phala cvms attestation [app-id]
 ```

 **Critical**: This step confirms your application is running in a genuine TEE environment with cryptographic proof.

 ## TEE Development and Testing

 ### TEE Simulator (Local Testing)

 ```bash
 # Start TEE simulator
 npx phala simulator start

 # Stop TEE simulator
 npx phala simulator stop
 ```

 ### Demo Applications

 ```bash
 # Launch demo applications
 npx phala demo
 ```

 ### Node Management

 ```bash
 # List all available worker nodes
 npx phala nodes list
 # or
 npx phala nodes ls
 ```

 ## Private Registry Support

 For private Docker images, set these environment variables in your docker-compose file:

 ### DockerHub

 - `DSTACK_DOCKER_USERNAME` - Your DockerHub username
 - `DSTACK_DOCKER_PASSWORD` - Your DockerHub password or access token
 - `DSTACK_DOCKER_REGISTRY` - Registry URL (optional, defaults to DockerHub)

 ### AWS ECR

 - `DSTACK_AWS_ACCESS_KEY_ID` - AWS access key
 - `DSTACK_AWS_SECRET_ACCESS_KEY` - AWS secret key
 - `DSTACK_AWS_REGION` - AWS region
 - `DSTACK_AWS_ECR_REGISTRY` - Full ECR registry URL

 ## Example Docker Compose Configuration

 ```yaml
 version: '3.8'
 services:
  app:
    image: your-registry/your-app:latest
    environment:
      - NODE_ENV=production
      - API_KEY=${API_KEY}
      - DATABASE_URL=${DATABASE_URL}
    ports:
      - "3000:3000"
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    networks:
      - app-network

 networks:
  app-network:
    driver: bridge
 ```

 ## Complete Example Workflow

 ```bash
 # 1. Create account and authenticate
 npx phala free
 npx phala auth login <your-api-key>
 npx phala auth status

 # 2. Prepare your application
 # - Create Dockerfile for your application
 # - Create docker-compose.yaml
 # - Prepare .env file with environment variables

 # 3. Build and deploy with Docker
 npx phala docker build
 npx phala docker push
 npx phala docker generate

 # 4. Create CVM
 npx phala cvms create -n my-app -c docker-compose.yaml -e .env

 # 5. Verify deployment
 npx phala cvms list
 npx phala cvms attestation
 ```

 ## Getting Help

 ```bash
 # General help
 npx phala help

 # Command-specific help
 npx phala <command> --help

 # Examples:
 npx phala auth --help
 npx phala cvms --help
 npx phala cvms create --help
 npx phala docker --help
 ```

 ## Common Issues and Troubleshooting

 ### Authentication Issues

 ```bash
 # Check current auth status
 npx phala auth status

 # Re-login if needed
 npx phala auth logout
 npx phala auth login <your-api-key>
 ```

 ### CVM Management Issues

 ```bash
 # Check CVM status
 npx phala cvms list
 npx phala cvms get <app-id>

 # Restart if needed
 npx phala cvms restart <app-id>

 # Check available nodes
 npx phala cvms list-nodes
 ```

 ### Docker Issues

 ```bash
 # Ensure Docker is running
 docker ps

 # Login to Docker Hub through Phala CLI
 npx phala docker login
 ```

 ### Resource Issues

 ```bash
 # Check CVM details for resource usage
 npx phala cvms get <app-id>

 # Resize if needed
 npx phala cvms resize <app-id> --vcpu 4 --memory 8192 --disk-size 80
 ```

 ## Security Best Practices

 ### Environment Configuration

 - **Private Keys**: Never expose in logs, environment files, or code
 - **API Keys**: Use secure environment variable injection via `-e` flag
 - **Attestation**: Always verify TEE attestation before handling sensitive operations
 - **Network Security**: Use HTTPS for all external communications

 ### Key Management

 - **Hardware Protection**: Leverage TEE's hardware-based key protection
 - **Secure Channels**: All external communications must use TLS
 - **Regular Verification**: Use `npx phala cvms attestation` to verify secure execution

 ### Docker Security

 ```yaml
 # Security-focused docker-compose.yaml
 services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=100m
    user: "1000:1000"  # Non-root user
 ```

 ## Application Types Suitable for TEE

 ### High Security Applications

 - **Cryptocurrency wallets and trading bots**
 - **Identity verification systems**
 - **Medical data processing**
 - **Financial calculation engines**
 - **AI inference with sensitive data**

 ### Benefits for Each Type

 - **Confidentiality**: Data processing in encrypted memory
 - **Integrity**: Cryptographic proof of execution environment
 - **Availability**: Distributed infrastructure with high uptime
 - **Compliance**: Meets regulatory requirements for data protection

 ## Resource Planning

 ### CVM Resource Guidelines

 - **Small Apps**: 1-2 vCPU, 2-4GB RAM, 20-40GB disk
 - **Medium Apps**: 2-4 vCPU, 4-8GB RAM, 40-80GB disk
 - **Large Apps**: 4+ vCPU, 8+ GB RAM, 80+ GB disk

 ### Cost Optimization

 - Start with minimal resources and scale up based on usage
 - Use `npx phala cvms resize` to adjust resources dynamically
 - Monitor application performance and resource utilization
 - Stop non-production CVMs when not in use

 ## References

 - [Phala Cloud Documentation](https://docs.phala.network/phala-cloud)
 - [Phala Cloud Dashboard](https://cloud.phala.network)
 - [Official Phala CLI](https://www.npmjs.com/package/phala)
 - [TEE Technology Overview](https://docs.phala.network/developers/dstack-guide)
 - [Confidential Computing Consortium](https://confidentialcomputing.io/)

 ---

 **Note**: The Phala CLI is automatically downloaded via npx if not already installed. All commands work with any containerized application that can run in a Docker environment.

 ---

 ## ⚠️ CRITICAL: Platform Architecture Requirements

 ### **Docker Architecture Compatibility for TEE Deployment**

 **Phala Cloud TEE infrastructure REQUIRES `linux/amd64` architecture.** Deploying images built for other architectures will result in deployment failures.

 #### **Why This Matters:**

 - TEE (Trusted Execution Environment) hardware is based on x86_64/amd64 processors
 - ARM-based images (`linux/arm64`) cannot run in TEE environments
 - Most deployment failures are caused by incorrect image architecture

 #### **Platform Detection & Solutions:**

 **✅ RECOMMENDED: Use Phala CLI (Automatic Platform Handling)**

 ```bash
 # Phala CLI automatically detects your platform and builds for linux/amd64
 npx phala docker build -i your-image -t your-tag

 # Example output showing automatic platform conversion:
 # "Detected platform: darwin/arm64, converting to linux/amd64 for TEE compatibility"
 ```

 **⚠️ MANUAL DOCKER COMMANDS: Must Specify Platform**

 ```bash
 # ❌ WRONG: Uses your local architecture (may be arm64 on Apple Silicon)
 docker build -t your-image:tag .

 # ✅ CORRECT: Forces linux/amd64 architecture for TEE compatibility  
 docker build --platform=linux/amd64 -t your-image:tag .

 # ✅ ALTERNATIVE: Use buildx for multi-platform builds
 docker buildx build --platform=linux/amd64 -t your-image:tag .
 ```

 #### **Platform Verification Commands:**

 ```bash
 # Check your system architecture
 uname -m                    # Shows: arm64 (Apple M1/M2) or x86_64 (Intel)
 docker version --format '{{.Server.Arch}}'

 # Verify image architecture before deploying
 docker image inspect your-image:tag --format '{{.Architecture}}'
 # Must show: amd64 (NOT arm64)
 ```

 #### **Platform Compatibility Matrix:**

 | Your System | Default Docker Build | TEE Compatible | Action Required |
 |-------------|---------------------|----------------|-----------------|
 | **Apple M1/M2 Mac** | `linux/arm64` | ❌ **FAILS** | Use `--platform=linux/amd64` |
 | **Intel Mac** | `linux/amd64` | ✅ Works | None |
 | **Linux x86_64** | `linux/amd64` | ✅ Works | None |
 | **Linux ARM64** | `linux/arm64` | ❌ **FAILS** | Use `--platform=linux/amd64` |
 | **Windows x64** | `linux/amd64` | ✅ Works | None |

 #### **Common Error Symptoms:**

 - CVM status shows "Failed", "Error", or "Stopped"
 - Container starts but immediately crashes
 - Application doesn't respond after deployment
 - Logs show "exec format error" or architecture mismatch

 #### **Quick Fix for Existing Images:**

 ```bash
 # If you already have an arm64 image, rebuild it:
 docker build --platform=linux/amd64 -t your-image:tag .
 docker push your-image:tag

 # Then upgrade your CVM:
 npx phala cvms upgrade your-app-id -c docker-compose.yaml -e .env
 ```

 #### **Best Practices:**

 1. **Always use `npx phala docker build`** - it handles platform automatically
 2. **If using Docker directly:** Always include `--platform=linux/amd64`  
 3. **Verify before pushing:** Check image architecture with `docker image inspect`
 4. **Update CI/CD:** Ensure build pipelines specify `--platform=linux/amd64`