Esa Deploy

Alibaba Cloud ESA Pages Deployment

Overview

ESA Pages is Alibaba Cloud's edge computing platform for static site hosting with global CDN acceleration. This skill automates deployment workflows for React/Vite applications.

Prerequisites

1. ESA CLI installed: npm install esa-cli@latest -g 2. Alibaba Cloud account with AccessKey configured 3. Logged in: esa-cli login

Quick Start

# Navigate to app directory
cd app

# Build and deploy
npm run build && esa-cli deploy

ESA CLI Commands

Authentication

# Login to ESA (requires AccessKey)
esa-cli login

# Logout
esa-cli logout

Deployment

# Deploy current directory (requires esa.jsonc)
esa-cli deploy

# Deploy with explicit entry
esa-cli deploy ./dist

# View deployments
esa-cli deployments

Project Management

# Initialize new project
esa-cli init my-project

# View project info
esa-cli project

# Manage sites
esa-cli site

Domain Management

# Add custom domain
esa-cli domain add your-domain.com

# List domains
esa-cli domain list

# Remove domain
esa-cli domain remove your-domain.com

Route Management

# Add route
esa-cli route add -r your-domain.com -s <site-name>

# List routes
esa-cli route list

Local Development

# Start local dev server
esa-cli dev

# Dev with custom port
esa-cli dev --port 3000

Configuration

esa.jsonc

{
  "name": "your-app-name",
  "assets": {
    "directory": "./dist",
    "notFoundStrategy": "singlePageApplication"
  },
  "dev": {
    "port": 18080
  }
}

Environment Variables

Production environment variables should be set in .env.local before build:

# Required
VITE_SUPABASE_URL=https://xxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJxxx...

# Production settings
VITE_ENABLE_MSW=false
VITE_LOG_LEVEL=info

Deployment Checklist

• [ ] Close MSW Mock (VITE_ENABLE_MSW=false)
• [ ] Verify environment variables are correct
• [ ] Run npm run build successfully
• [ ] Check dist/ directory exists
• [ ] Verify esa.jsonc configuration
• [ ] Run esa-cli deploy

Common Issues

"esa.jsonc not found"

Ensure you're in the correct directory containing esa.jsonc:

cd app && esa-cli deploy

"Not logged in"

esa-cli login

Build fails

# Check Node version (>= 20.x)
node -v

# Clean install
rm -rf node_modules && npm install

# Rebuild
npm run build

Large bundle warning

Consider code splitting:

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'react-vendor': ['react', 'react-dom'],
          'ui-vendor': ['@radix-ui/react-dialog', '@radix-ui/react-dropdown-menu'],
        },
      },
    },
  },
});

Deployment Output

After successful deployment:

╔═══════════════════════════════════════════════════════════════════════╗
║ 🚀 Deploy Success                                                     ║
║                                                                       ║
║ APP  your-app-name                                                    ║
║ URL  https://your-app.xxx.er.aliyun-esa.net                           ║
║                                                                       ║
║ TIP  Add a custom domain: esa-cli domain add <DOMAIN>                 ║
╚═══════════════════════════════════════════════════════════════════════╝

References

• Environment Configuration references/environment-config.md
• Custom Domain Setup references/custom-domain.md
• CI/CD Integration references/cicd-integration.md

CI/CD Integration for ESA Deployment

GitHub Actions

Basic Workflow

# .github/workflows/deploy.yml
name: Deploy to ESA

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: app/package-lock.json

      - name: Install Dependencies
        working-directory: ./app
        run: npm ci

      - name: Build
        working-directory: ./app
        env:
          VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
          VITE_SUPABASE_ANON_KEY: ${{ secrets.VITE_SUPABASE_ANON_KEY }}
          VITE_ENABLE_MSW: false
          VITE_LOG_LEVEL: info
        run: npm run build

      - name: Install ESA CLI
        run: npm install esa-cli@latest -g

      - name: Configure ESA Credentials
        env:
          ESA_ACCESS_KEY_ID: ${{ secrets.ESA_ACCESS_KEY_ID }}
          ESA_ACCESS_KEY_SECRET: ${{ secrets.ESA_ACCESS_KEY_SECRET }}
        run: |
          esa-cli config set accessKeyId $ESA_ACCESS_KEY_ID
          esa-cli config set accessKeySecret $ESA_ACCESS_KEY_SECRET

      - name: Deploy
        working-directory: ./app
        run: esa-cli deploy

Required GitHub Secrets

GitLab CI

# .gitlab-ci.yml
stages:
  - deploy

deploy_esa:
  stage: deploy
  image: node:20
  only:
    - main
  script:
    - cd app
    - npm ci
    - npm run build
    - npm install esa-cli@latest -g
    - esa-cli config set accessKeyId $ESA_ACCESS_KEY_ID
    - esa-cli config set accessKeySecret $ESA_ACCESS_KEY_SECRET
    - esa-cli deploy
  variables:
    VITE_SUPABASE_URL: $VITE_SUPABASE_URL
    VITE_SUPABASE_ANON_KEY: $VITE_SUPABASE_ANON_KEY
    VITE_ENABLE_MSW: "false"

Jenkins Pipeline

// Jenkinsfile
pipeline {
  agent any

  environment {
    VITE_SUPABASE_URL = credentials('supabase-url')
    VITE_SUPABASE_ANON_KEY = credentials('supabase-anon-key')
    ESA_ACCESS_KEY_ID = credentials('esa-access-key-id')
    ESA_ACCESS_KEY_SECRET = credentials('esa-access-key-secret')
  }

  stages {
    stage('Install') {
      steps {
        dir('app') {
          sh 'npm ci'
        }
      }
    }

    stage('Build') {
      environment {
        VITE_ENABLE_MSW = 'false'
        VITE_LOG_LEVEL = 'info'
      }
      steps {
        dir('app') {
          sh 'npm run build'
        }
      }
    }

    stage('Deploy') {
      steps {
        sh 'npm install esa-cli@latest -g'
        sh "esa-cli config set accessKeyId ${ESA_ACCESS_KEY_ID}"
        sh "esa-cli config set accessKeySecret ${ESA_ACCESS_KEY_SECRET}"
        dir('app') {
          sh 'esa-cli deploy'
        }
      }
    }
  }
}

Deployment Strategies

Blue-Green Deployment

1. Deploy to staging environment first 2. Run smoke tests 3. Promote to production

# GitHub Actions - Blue-Green
deploy-staging:
  runs-on: ubuntu-latest
  environment: staging
  steps:
    - name: Deploy to Staging
      # ... deploy steps

deploy-production:
  needs: deploy-staging
  runs-on: ubuntu-latest
  environment: production
  steps:
    - name: Deploy to Production
      # ... deploy steps

Preview Deployments

Deploy pull requests to preview URLs:

deploy-preview:
  runs-on: ubuntu-latest
  if: github.event_name == 'pull_request'
  steps:
    - name: Deploy Preview
      working-directory: ./app
      run: |
        esa-cli deploy --name "pr-${{ github.event.pull_request.number }}"

Rollback

Manual Rollback

# List deployments
esa-cli deployments

# Rollback to specific version
esa-cli deployments rollback <deployment-id>

Automated Rollback

# GitHub Actions with auto-rollback
- name: Health Check
  run: |
    response=$(curl -s -o /dev/null -w "%{http_code}" https://your-domain.com)
    if [ "$response" != "200" ]; then
      esa-cli deployments rollback previous
      exit 1
    fi

Security Considerations

1. Use GitHub Environments for production protection 2. Limit AccessKey permissions to ESA only 3. Enable branch protection for main branch 4. Use OIDC for cloud authentication (if supported) 5. Rotate secrets regularly

Custom Domain Setup for ESA Pages

Prerequisites

• Domain name (purchased from any registrar)
• ICP filing (required for mainland China access)
• DNS management access

Step-by-Step Guide

1. Add Custom Domain

esa-cli domain add your-domain.com

Or for subdomain:

esa-cli domain add app.your-domain.com

2. Configure DNS

Add CNAME record in your DNS management:

3. Configure HTTPS

ESA supports automatic SSL certificate issuance:

1. ESA Console → Your Site → Domain Management 2. Click on domain → SSL Certificate 3. Select "Auto-apply free certificate" 4. Wait for verification (usually within minutes)

Alternatively, upload your own certificate:

esa-cli domain cert-upload your-domain.com --cert=./cert.pem --key=./key.pem

4. Update Supabase Configuration

After domain is active, update Supabase settings:

1. Go to Supabase Dashboard → Authentication → URL Configuration 2. Update Site URL to your custom domain 3. Add domain to Redirect URLs allowlist

5. Verify Deployment

# Check domain status
esa-cli domain list

# Test access
curl -I https://your-domain.com

Domain Strategies

Single Domain

your-domain.com → ESA Pages

Subdomain Strategy

app.your-domain.com    → Frontend (ESA Pages)
api.your-domain.com    → Backend API
admin.your-domain.com  → Admin Panel

Multi-region Strategy

your-domain.com      → Global (ESA auto-routes)
cn.your-domain.com   → China region
us.your-domain.com   → US region

Troubleshooting

Domain Not Resolving

1. Check DNS propagation: dig your-domain.com 2. Verify CNAME record is correct 3. Wait up to 48 hours for full propagation

SSL Certificate Issues

1. Ensure domain is verified in ESA console 2. Check certificate status in ESA dashboard 3. Try re-issuing certificate

CORS Errors

1. Update Supabase allowed origins 2. Check Edge Function CORS configuration 3. Verify frontend API base URL

ICP Filing (China Mainland)

For websites accessible in mainland China:

1. Submit ICP filing through Alibaba Cloud 2. Wait for approval (10-20 business days) 3. Display ICP number in footer 4. Link to MIIT website

Reference: https://beian.aliyun.com/

Environment Configuration for ESA Deployment

Frontend Environment Variables

Required Variables

Optional Variables

Production Configuration

Before Deployment

1. Disable Mock Services

   # .env.local
   VITE_ENABLE_MSW=false

2. Set Appropriate Log Level

   VITE_LOG_LEVEL=info  # or 'warn' for less verbosity

3. Verify Supabase Configuration

• Check Supabase project is active
• Verify RLS policies are configured
• Ensure Edge Functions are deployed

Edge Function Secrets

These are configured in Supabase Dashboard → Edge Functions → Secrets:

Security Best Practices

1. Never commit `.env.local` to version control 2. Use different Supabase projects for dev/staging/prod 3. Rotate API keys periodically 4. Use RAM sub-accounts with minimal permissions

Environment File Template

# .env.local.example - Copy to .env.local and fill in values

# ============================================
# Supabase Configuration (Required)
# ============================================
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key_here

# ============================================
# Production Settings
# ============================================
VITE_ENABLE_MSW=false
VITE_LOG_LEVEL=info

# ============================================
# Optional: OSS Acceleration
# ============================================
VITE_OSS_ACCELERATE_ENABLED=false