Claude Code Cloud Server Deployment Guide

This guide provides detailed instructions for deploying a VitePress project on a cloud server using PM2 for process management, ensuring the service continues running even after SSH disconnection.

🛠 System Requirements

Operating System: Linux (Ubuntu/CentOS)
Node.js: v22.11.0 (installed at /www/server/nodejs/v22.11.0/bin)
PM2: Process manager
Memory: Minimum 512MB
Storage: Minimum 1GB free space

📋 Deployment Steps

1. Server Environment Setup

1.1 Node.js Environment Variables Configuration

bash

# Add to ~/.bashrc or ~/.profile
echo 'export PATH=$PATH:/www/server/nodejs/v22.11.0/bin' >> ~/.bashrc
source ~/.bashrc

# Verify Node.js version
node --version
npm --version

1.2 Create Project Directory

bash

# Create project directory
mkdir -p /www/wwwroot/claudecode
cd /www/wwwroot/claudecode

2. Upload Project Files

2.1 Using SCP to Upload (Recommended)

bash

# Run locally (replace your-server-ip with actual IP)
scp -r /c:/Users/PC/Desktop/claudecode.blueshirtmap.com_eN7Pt/* root@your-server-ip:/www/wwwroot/claudecode/

2.2 Using Git Clone (if Git repository exists)

bash

# Run on server
git clone https://github.com/your-username/claudecode.git .

3. Install Project Dependencies

bash

# Navigate to project directory
cd /www/wwwroot/claudecode

# Install project dependencies
npm install

# If permission issues occur, use
npm install --unsafe-perm

4. Build Production Version

bash

# Build project
npm run docs:build

# Verify build result
ls -la .vitepress/dist/

5. PM2 Installation and Configuration

5.1 Install PM2 Globally

bash

npm install -g pm2

# Verify installation
pm2 --version

5.2 Create PM2 Configuration File

bash

# Create PM2 configuration file
cat > ecosystem.config.js << 'EOF'
module.exports = {
  apps: [
    {
      name: 'claudecode-docs',
      script: 'npm',
      args: 'run docs:preview',
      cwd: '/www/wwwroot/claudecode',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production',
        PORT: 4173
      },
      error_file: '/www/wwwroot/claudecode/logs/err.log',
      out_file: '/www/wwwroot/claudecode/logs/out.log',
      log_file: '/www/wwwroot/claudecode/logs/combined.log',
      time: true,
      restart_delay: 1000,
      max_restarts: 5,
      min_uptime: '10s',
      max_memory_restart: '1G',
      watch: false,
      ignore_watch: ['node_modules', 'logs', '.git']
    }
  ]
}
EOF

5.3 Create Logs Directory

bash

mkdir -p /www/wwwroot/claudecode/logs

6. Start Service

6.1 Start Project with PM2

bash

# Start service
pm2 start ecosystem.config.js

# Check service status
pm2 status

# View logs
pm2 logs claudecode-docs

6.2 Configure PM2 Auto-start

bash

# Save PM2 configuration
pm2 save

# Configure auto-start
pm2 startup
# Execute the command shown by the previous command (usually sudo command)

7. Reverse Proxy Configuration (Optional)

If domain name access is needed, you can configure Nginx reverse proxy:

7.1 Nginx Configuration Example

nginx

server {
    listen 80;
    server_name claudecode.blueshirtmap.com;
    
    location / {
        proxy_pass http://localhost:4173;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Static files cache
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
            proxy_pass http://localhost:4173;
        }
    }
}

8. Deployment Verification

8.1 Check Service Status

bash

# View PM2 status
pm2 status

# View process details
pm2 show claudecode-docs

# View real-time logs
pm2 logs claudecode-docs --lines 50

8.2 Test Website Access

bash

# Local test
curl -I http://localhost:4173

# Remote test (replace with actual IP)
curl -I http://your-server-ip:4173

🔧 Commonly Used PM2 Commands

Basic Commands

bash

# Start service
pm2 start ecosystem.config.js

# Stop service
pm2 stop claudecode-docs

# Restart service
pm2 restart claudecode-docs

# Delete service
pm2 delete claudecode-docs

# View all services
pm2 list

# View service details
pm2 show claudecode-docs

Log Management

bash

# View logs
pm2 logs claudecode-docs

# View error logs
pm2 logs claudecode-docs --err

# Clear logs
pm2 flush claudecode-docs

# View logs with line count
pm2 logs claudecode-docs --lines 100

Process Monitoring

bash

# Real-time monitoring
pm2 monit

# View process resource usage
pm2 show claudecode-docs

# Reload service (zero downtime)
pm2 reload claudecode-docs

🚨 Troubleshooting

Common Issues and Solutions

1. Service Won't Start

bash

# Check logs
pm2 logs claudecode-docs

# Check if port is occupied
netstat -tulpn | grep 4173

# Manual start to check for errors
cd /www/wwwroot/claudecode
npm run docs:preview

2. Permission Issues

bash

# Check directory permissions
ls -la /www/wwwroot/claudecode

# Fix permissions
sudo chown -R $USER:$USER /www/wwwroot/claudecode
chmod -R 755 /www/wwwroot/claudecode

3. Node.js Path Issues

bash

# Check Node.js path
which node
which npm

# Re-configure environment variables
export PATH=$PATH:/www/server/nodejs/v22.11.0/bin
source ~/.bashrc

4. Memory Issues

bash

# Check memory usage
free -h

# View PM2 process memory usage
pm2 monit

# Adjust max_memory_restart in ecosystem.config.js

Emergency Commands

bash

# Kill all PM2 processes
pm2 kill

# Restart PM2 daemon
pm2 resurrect

# Update PM2
npm update -g pm2

📊 Performance Optimization

1. Enable Gzip Compression

Add to Nginx configuration:

nginx

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss;

2. Configure Cache Headers

nginx

location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

3. Log Rotation

bash

# Install logrotate
sudo apt-get install logrotate

# Create logrotate configuration
cat > /etc/logrotate.d/claudecode << 'EOF'
/www/wwwroot/claudecode/logs/*.log {
    daily
    missingok
    rotate 52
    compress
    notifempty
    create 644 root root
    postrotate
        pm2 reloadLogs
    endscript
}
EOF

🔐 Security Considerations

1. Firewall Configuration

bash

# Open port 4173 (if using direct access)
sudo ufw allow 4173

# Or only allow from specific IPs
sudo ufw allow from your-ip to any port 4173

2. Regular Updates

bash

# Update system packages
sudo apt update && sudo apt upgrade

# Update Node.js dependencies
npm audit
npm update

3. SSL Certificate (if using domain)

bash

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d claudecode.blueshirtmap.com

📝 Maintenance

Regular Maintenance Tasks

bash

# View service health
pm2 status

# Check disk space
df -h

# Monitor system resources
htop

# Check service logs
pm2 logs claudecode-docs --lines 50

Backup Strategy

bash

# Backup project files
tar -czf claudecode-backup-$(date +%Y%m%d).tar.gz /www/wwwroot/claudecode

# Backup PM2 configuration
pm2 save
cp ~/.pm2/dump.pm2 ~/pm2-backup-$(date +%Y%m%d).json

This completes the comprehensive deployment guide for Claude Code on a cloud server using PM2 process management.

Claude Code Cloud Server Deployment Guide ​

🛠 System Requirements ​

📋 Deployment Steps ​

1. Server Environment Setup ​

1.1 Node.js Environment Variables Configuration ​

1.2 Create Project Directory ​

2. Upload Project Files ​

2.1 Using SCP to Upload (Recommended) ​

2.2 Using Git Clone (if Git repository exists) ​

3. Install Project Dependencies ​

4. Build Production Version ​

5. PM2 Installation and Configuration ​

5.1 Install PM2 Globally ​

5.2 Create PM2 Configuration File ​

5.3 Create Logs Directory ​

6. Start Service ​

6.1 Start Project with PM2 ​

6.2 Configure PM2 Auto-start ​

7. Reverse Proxy Configuration (Optional) ​

7.1 Nginx Configuration Example ​

8. Deployment Verification ​

8.1 Check Service Status ​

8.2 Test Website Access ​

🔧 Commonly Used PM2 Commands ​

Basic Commands ​

Log Management ​

Process Monitoring ​

🚨 Troubleshooting ​

Common Issues and Solutions ​

1. Service Won't Start ​

2. Permission Issues ​

3. Node.js Path Issues ​

4. Memory Issues ​

Emergency Commands ​

📊 Performance Optimization ​

1. Enable Gzip Compression ​

2. Configure Cache Headers ​

3. Log Rotation ​

🔐 Security Considerations ​

1. Firewall Configuration ​

2. Regular Updates ​

3. SSL Certificate (if using domain) ​

📝 Maintenance ​

Regular Maintenance Tasks ​

Backup Strategy ​

Claude Code Cloud Server Deployment Guide

🛠 System Requirements

📋 Deployment Steps

1. Server Environment Setup

1.1 Node.js Environment Variables Configuration

1.2 Create Project Directory

2. Upload Project Files

2.1 Using SCP to Upload (Recommended)

2.2 Using Git Clone (if Git repository exists)

3. Install Project Dependencies

4. Build Production Version

5. PM2 Installation and Configuration

5.1 Install PM2 Globally

5.2 Create PM2 Configuration File

5.3 Create Logs Directory

6. Start Service

6.1 Start Project with PM2

6.2 Configure PM2 Auto-start

7. Reverse Proxy Configuration (Optional)

7.1 Nginx Configuration Example

8. Deployment Verification

8.1 Check Service Status

8.2 Test Website Access

🔧 Commonly Used PM2 Commands

Basic Commands

Log Management

Process Monitoring

🚨 Troubleshooting

Common Issues and Solutions

1. Service Won't Start

2. Permission Issues

3. Node.js Path Issues

4. Memory Issues

Emergency Commands

📊 Performance Optimization

1. Enable Gzip Compression

2. Configure Cache Headers

3. Log Rotation

🔐 Security Considerations

1. Firewall Configuration

2. Regular Updates

3. SSL Certificate (if using domain)

📝 Maintenance

Regular Maintenance Tasks

Backup Strategy