mikamirAI Deployment Runbook

Overview

This runbook provides comprehensive instructions for deploying the mikamirAI trading research website to Azure Static Web Apps. It includes both automated and manual deployment processes, troubleshooting guides, and best practices.

Table of Contents

1. Prerequisites
2. Automated Deployment
3. Manual Deployment
4. Environment Configuration
5. Troubleshooting
6. Rollback Procedures
7. Post-Deployment Verification
8. Monitoring and Maintenance

Prerequisites

Required Software

Azure Prerequisites

1. Azure Account: Active Azure subscription
2. Resource Group: mikamirai-rg (or your preferred name)
3. Static Web App: mikamirai-static-app (or your preferred name)
4. Permissions: Contributor access to the resource group

GitHub Prerequisites

1. Repository: GitHub repository with the project code
2. Access: Push permissions to the repository
3. Branch: Main branch should be protected and up-to-date

Automated Deployment

Quick Start

The automated deployment script handles the entire deployment process:

# For Linux/macOS
./scripts/deploy.sh

# For Windows (PowerShell)
.\scripts\deploy.ps1

Script Features

• ✅ Prerequisites validation
• ✅ Dependency installation
• ✅ Code quality checks (TypeScript, ESLint)
• ✅ Application build
• ✅ Git commit and push
• ✅ Azure deployment
• ✅ Health checks
• ✅ Deployment logging

Script Options

Linux/macOS (Bash)

# Basic deployment
./scripts/deploy.sh

# Custom Azure resources
./scripts/deploy.sh --resource-group "my-rg" --app-name "my-app"

# Skip build step (if already built)
./scripts/deploy.sh --skip-build

# Skip git operations
./scripts/deploy.sh --skip-commit

# Show help
./scripts/deploy.sh --help

Windows (PowerShell)

# Basic deployment
.\scripts\deploy.ps1

# Custom Azure resources
.\scripts\deploy.ps1 -ResourceGroup "my-rg" -AppName "my-app"

# Skip build step
.\scripts\deploy.ps1 -SkipBuild

# Skip git operations
.\scripts\deploy.ps1 -SkipCommit

# Show help
.\scripts\deploy.ps1 -Help

Deployment Logs

All deployment activities are logged to:

• Location: logs/deployment-YYYY-MM-DD.log
• Format: Timestamped entries with deployment steps
• Retention: Manual cleanup (consider archiving old logs)

Manual Deployment

Step 1: Environment Setup

# 1. Clone the repository
git clone https://github.com/yourusername/mikamiraispa.git
cd mikamiraispa

# 2. Install dependencies
npm ci

# 3. Login to Azure
az login

# 4. Set default subscription (if needed)
az account set --subscription "your-subscription-id"

Step 2: Code Quality Checks

# 1. TypeScript type checking
npx tsc --noEmit

# 2. Linting (if configured)
npx eslint . --ext .ts,.tsx,.js,.jsx --max-warnings 0

# 3. Run tests (if available)
npm test

Step 3: Build Application

# 1. Clean previous build
rm -rf out

# 2. Build the application
npm run build

# 3. Verify build output
ls -la out/

Step 4: Commit and Push Changes

# 1. Check status
git status

# 2. Add changes
git add .

# 3. Commit changes
git commit -m "Deploy: $(date '+%Y-%m-%d %H:%M:%S') - Manual deployment"

# 4. Push to GitHub
git push origin main

Step 5: Deploy to Azure

# Deploy to Azure Static Web Apps
az staticwebapp deploy \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --source "out"

Step 6: Verify Deployment

# Get deployment URL
az staticwebapp show \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --query "defaultHostname" \
  --output tsv

# Test the deployment
curl -I https://your-app-url.azurestaticapps.net

Environment Configuration

Azure Static Web App Configuration

Required Settings

{
  "name": "mikamirai-static-app",
  "resourceGroup": "mikamirai-rg",
  "location": "Central US",
  "sku": "Free",
  "buildProperties": {
    "appLocation": "/",
    "outputLocation": "out"
  }
}

Custom Domain Setup

1. Add Custom Domain:

   az staticwebapp hostname set \
     --name "mikamirai-static-app" \
     --resource-group "mikamirai-rg" \
     --hostname "mikamirai.com"
   

2. Configure DNS:

   • Add CNAME record: www.mikamirai.com → your-app.azurestaticapps.net
   • Add A record: mikamirai.com → Static Web App IP

3. SSL Certificate:

   • Automatically provisioned by Azure
   • Validates within 24 hours

Environment Variables

Create a .env.local file for local development:

# Local development environment
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id

Production environment variables are configured in Azure Static Web Apps:

# Set production environment variable
az staticwebapp appsettings set \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --setting-names "NEXT_PUBLIC_SITE_URL=https://mikamirai.com"

Troubleshooting

Common Issues

1. Build Failures

Symptoms: Build process fails with errors

Solutions:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version  # Should be 18.x or higher

# Run build with verbose output
npm run build --verbose

2. TypeScript Errors

Symptoms: Type checking fails

Solutions:

# Check TypeScript configuration
npx tsc --showConfig

# Fix type errors
npx tsc --noEmit --listFiles

# Update TypeScript dependencies
npm update typescript @types/node @types/react

3. Azure CLI Issues

Symptoms: Azure commands fail

Solutions:

# Check Azure CLI version
az --version

# Update Azure CLI
az upgrade

# Re-login to Azure
az logout
az login

# Check subscription
az account show

4. Git Issues

Symptoms: Git operations fail

Solutions:

# Check git configuration
git config --list

# Configure git (if needed)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Check remote origin
git remote -v

# Fix remote URL (if needed)
git remote set-url origin https://github.com/yourusername/mikamiraispa.git

5. Deployment Failures

Symptoms: Azure deployment fails

Solutions:

# Check Static Web App exists
az staticwebapp show \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg"

# Check deployment logs
az staticwebapp show \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --query "repositoryUrl"

# Redeploy manually
az staticwebapp deploy \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --source "out" \
  --verbose

Error Codes

Rollback Procedures

Immediate Rollback

If the deployment fails or causes issues:

1. Identify Last Good Commit:

   git log --oneline -10
   

2. Revert to Previous Version:

   # Revert to specific commit
   git revert HEAD --no-edit
   
   # Or reset to previous commit (destructive)
   git reset --hard HEAD~1
   

3. Redeploy:

   # Push the revert
   git push origin main
   
   # Deploy the reverted version
   ./scripts/deploy.sh
   

Rollback via Azure Portal

1. Navigate to Azure Static Web Apps
2. Select your app
3. Go to "Deployment history"
4. Select a previous successful deployment
5. Click "Revert"

Database Rollback (if applicable)

If using external databases:

1. Backup Current State:

   # Create backup before rollback
   az sql db export \
     --resource-group "mikamirai-rg" \
     --server "mikamirai-sql" \
     --name "mikamirai-db" \
     --storage-key "your-storage-key" \
     --storage-key-type "StorageAccessKey" \
     --storage-uri "https://storage.blob.core.windows.net/backups/rollback-$(date +%Y%m%d).bacpac"
   

2. Restore Previous Backup:

   # Restore from backup
   az sql db import \
     --resource-group "mikamirai-rg" \
     --server "mikamirai-sql" \
     --name "mikamirai-db" \
     --storage-key "your-storage-key" \
     --storage-key-type "StorageAccessKey" \
     --storage-uri "https://storage.blob.core.windows.net/backups/previous-backup.bacpac"
   

Post-Deployment Verification

Automated Verification

The deployment script includes automated health checks:

• ✅ HTTP status code verification
• ✅ Response time measurement
• ✅ SSL certificate validation
• ✅ DNS resolution check

Manual Verification Checklist

1. Website Functionality

• Homepage loads correctly
• Navigation works
• Blog pages display properly
• TradingView widget loads
• Mobile responsiveness
• Search functionality (if applicable)

2. Performance Checks

# Check page load times
curl -w "@curl-format.txt" -o /dev/null -s "https://mikamirai.com"

# Check resource loading
curl -I "https://mikamirai.com/_next/static/css/styles.css"

3. SEO Verification

• Meta tags present
• Sitemap accessible (/sitemap.xml)
• Robots.txt accessible (/robots.txt)
• Structured data validation
• Open Graph tags

4. Security Checks

# Check SSL certificate
openssl s_client -connect mikamirai.com:443 -servername mikamirai.com

# Check security headers
curl -I "https://mikamirai.com"

Monitoring Setup

Azure Monitor

1. Enable Application Insights:

   az monitor app-insights component create \
     --app "mikamirai-insights" \
     --location "Central US" \
     --resource-group "mikamirai-rg"
   

2. Configure Alerts:

   # Create availability test
   az monitor app-insights web-test create \
     --resource-group "mikamirai-rg" \
     --name "mikamirai-availability" \
     --location "Central US" \
     --web-test-name "Homepage Test" \
     --web-test-kind "ping" \
     --url "https://mikamirai.com"
   

External Monitoring

Consider using external monitoring services:

• Uptime Robot: Free tier available
• Pingdom: Comprehensive monitoring
• StatusCake: Free and paid plans
• New Relic: Application performance monitoring

Monitoring and Maintenance

Regular Maintenance Tasks

Daily

• Check deployment logs
• Monitor website availability
• Review error logs (if any)

Weekly

• Update dependencies
• Review performance metrics
• Check security advisories
• Backup configuration

Monthly

• Update Azure CLI and tools
• Review and archive old logs
• Performance optimization review
• Security audit

Maintenance Commands

# Update dependencies
npm update

# Check for security vulnerabilities
npm audit

# Fix security issues
npm audit fix

# Update Azure CLI
az upgrade

# Clean up old deployments (if needed)
az staticwebapp deployment list \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg"

Performance Optimization

Monitoring Performance

# Lighthouse audit
npm install -g lighthouse
lighthouse https://mikamirai.com --output json --output-path ./lighthouse-report.json

# Bundle analyzer (if configured)
npm run analyze

Optimization Techniques

1. Image Optimization:

   • Use WebP format
   • Implement lazy loading
   • Optimize image sizes

2. Code Optimization:

   • Tree shaking
   • Code splitting
   • Minification

3. Caching:

   • Static asset caching
   • CDN configuration
   • Browser caching headers

Backup and Recovery

Code Backup

• Primary: GitHub repository
• Secondary: Azure DevOps (if configured)
• Local: Regular local backups

Configuration Backup

# Export Azure Static Web App configuration
az staticwebapp show \
  --name "mikamirai-static-app" \
  --resource-group "mikamirai-rg" \
  --output json > backup/staticwebapp-config.json

# Export DNS configuration
az network dns zone export \
  --resource-group "mikamirai-rg" \
  --name "mikamirai.com" \
  --file-name backup/dns-zone.txt

Emergency Contacts

Documentation Updates

This runbook should be updated:

• After each deployment process change
• When new tools are introduced
• After resolving new issues
• Quarterly review and updates

Appendix

Useful Commands Reference

# Check deployment status
az staticwebapp show --name "mikamirai-static-app" --resource-group "mikamirai-rg"

# View deployment logs
az staticwebapp logs --name "mikamirai-static-app" --resource-group "mikamirai-rg"

# List all deployments
az staticwebapp deployment list --name "mikamirai-static-app" --resource-group "mikamirai-rg"

# Get deployment URL
az staticwebapp show --name "mikamirai-static-app" --resource-group "mikamirai-rg" --query "defaultHostname" --output tsv

# Check build status
npm run build --verbose

# Test local build
npm run start

# Check dependencies
npm list --depth=0

Configuration Files

package.json Scripts

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "type-check": "tsc --noEmit",
    "deploy": "./scripts/deploy.sh"
  }
}

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  trailingSlash: true,
  images: {
    unoptimized: true
  }
}

module.exports = nextConfig

Document Version: 1.0
Last Updated: January 2025
Next Review: March 2025