CalejoControl/deploy/SSH_DEPLOYMENT.md

# SSH Deployment Guide

This guide explains how to deploy the Calejo Control Adapter to remote servers using SSH.

## 🚀 Quick Start

### 1. Setup SSH Keys

Generate and deploy SSH keys for each environment:

```bash
# Generate production key
ssh-keygen -t ed25519 -f deploy/keys/production_key -C "calejo-production-deploy" -N ""

# Deploy public key to production server
ssh-copy-id -i deploy/keys/production_key.pub calejo@production-server.company.com

# Set proper permissions
chmod 600 deploy/keys/*
```

### 2. Create Configuration

Copy the example configuration and customize:

```bash
# For production
cp deploy/config/example-production.yml deploy/config/production.yml

# Edit with your server details
nano deploy/config/production.yml
```

### 3. Deploy

```bash
# Deploy to production
./deploy/ssh/deploy-remote.sh -e production

# Dry run first
./deploy/ssh/deploy-remote.sh -e production --dry-run

# Verbose output
./deploy/ssh/deploy-remote.sh -e production --verbose
```

## 📁 Configuration Structure

```
deploy/
├── ssh/
│   └── deploy-remote.sh          # Main deployment script
├── config/
│   ├── example-production.yml    # Example production config
│   ├── example-staging.yml       # Example staging config
│   ├── production.yml            # Production config (gitignored)
│   └── staging.yml               # Staging config (gitignored)
└── keys/
    ├── README.md                 # Key management guide
    ├── production_key            # Production SSH key (gitignored)
    ├── production_key.pub        # Production public key (gitignored)
    ├── staging_key               # Staging SSH key (gitignored)
    └── staging_key.pub           # Staging public key (gitignored)
```

## 🔧 Configuration Files

### Production Configuration (`deploy/config/production.yml`)

```yaml
# SSH Connection Details
ssh:
  host: "production-server.company.com"
  port: 22
  username: "calejo"
  key_file: "deploy/keys/production_key"
  
# Deployment Settings
deployment:
  target_dir: "/opt/calejo-control-adapter"
  backup_dir: "/var/backup/calejo"
  log_dir: "/var/log/calejo"
  config_dir: "/etc/calejo"
  
# Application Configuration
app:
  port: 8080
  host: "0.0.0.0"
  debug: false
```

### Staging Configuration (`deploy/config/staging.yml`)

```yaml
ssh:
  host: "staging-server.company.com"
  port: 22
  username: "calejo"
  key_file: "deploy/keys/staging_key"
  
deployment:
  target_dir: "/opt/calejo-control-adapter"
  backup_dir: "/var/backup/calejo"
  log_dir: "/var/log/calejo"
  config_dir: "/etc/calejo"
```

## 🔑 SSH Key Management

### Generating Keys

```bash
# Generate ED25519 key (recommended)
ssh-keygen -t ed25519 -f deploy/keys/production_key -C "calejo-production" -N ""

# Generate RSA key (alternative)
ssh-keygen -t rsa -b 4096 -f deploy/keys/production_key -C "calejo-production" -N ""

# Set secure permissions
chmod 600 deploy/keys/production_key
chmod 644 deploy/keys/production_key.pub
```

### Deploying Public Keys

```bash
# Copy to remote server
ssh-copy-id -i deploy/keys/production_key.pub calejo@production-server.company.com

# Manual method
cat deploy/keys/production_key.pub | ssh calejo@production-server.company.com 'mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys'
```

### Testing SSH Connection

```bash
# Test connection
ssh -i deploy/keys/production_key calejo@production-server.company.com

# Test with specific port
ssh -i deploy/keys/production_key -p 2222 calejo@production-server.company.com
```

## 🛠️ Deployment Script Usage

### Basic Usage

```bash
# Deploy to staging
./deploy/ssh/deploy-remote.sh -e staging

# Deploy to production
./deploy/ssh/deploy-remote.sh -e production

# Use custom config file
./deploy/ssh/deploy-remote.sh -e production -c deploy/config/custom.yml
```

### Advanced Options

```bash
# Dry run (show what would be deployed)
./deploy/ssh/deploy-remote.sh -e production --dry-run

# Verbose output
./deploy/ssh/deploy-remote.sh -e production --verbose

# Help
./deploy/ssh/deploy-remote.sh --help
```

### Environment Variables

You can also use environment variables for sensitive data:

```bash
export CALEJO_DEPLOY_KEY_PATH="deploy/keys/production_key"
export CALEJO_DEPLOY_PASSPHRASE="your-passphrase"
```

## 🔄 Deployment Process

The deployment script performs the following steps:

1. **Configuration Validation**
   - Loads environment configuration
   - Validates SSH key and connection details
   - Checks remote prerequisites

2. **Remote Setup**
   - Creates necessary directories
   - Backs up existing deployment (if any)
   - Transfers application files

3. **Application Deployment**
   - Sets up remote configuration
   - Builds Docker images
   - Starts services
   - Waits for services to be ready

4. **Validation**
   - Runs deployment validation
   - Tests key endpoints
   - Generates deployment summary

## 🔒 Security Best Practices

### SSH Key Security

- **Use different keys** for different environments
- **Set proper permissions**: `chmod 600` for private keys
- **Use passphrase-protected keys** in production
- **Rotate keys regularly** (every 6-12 months)
- **Never commit private keys** to version control

### Server Security

- **Use non-root user** for deployment
- **Configure sudo access** for specific commands only
- **Use firewall** to restrict SSH access
- **Enable fail2ban** for SSH protection
- **Use SSH key authentication only** (disable password auth)

### Configuration Security

- **Store sensitive data** in environment variables
- **Use encrypted configuration** for production
- **Regularly audit** access logs
- **Monitor deployment activities**

## 🐛 Troubleshooting

### Common Issues

1. **SSH Connection Failed**
   ```bash
   # Check key permissions
   chmod 600 deploy/keys/production_key
   
   # Test connection manually
   ssh -i deploy/keys/production_key -v calejo@production-server.company.com
   ```

2. **Permission Denied**
   ```bash
   # Ensure user has sudo access
   ssh -i deploy/keys/production_key calejo@production-server.company.com 'sudo -v'
   ```

3. **Docker Not Installed**
   ```bash
   # Check Docker installation
   ssh -i deploy/keys/production_key calejo@production-server.company.com 'docker --version'
   ```

4. **Port Already in Use**
   ```bash
   # Check running services
   ssh -i deploy/keys/production_key calejo@production-server.company.com 'sudo netstat -tulpn | grep :8080'
   ```

### Debug Mode

Enable verbose output to see detailed execution:

```bash
./deploy/ssh/deploy-remote.sh -e production --verbose
```

### Log Files

- **Local logs**: Check script output
- **Remote logs**: `/var/log/calejo/` on target server
- **Docker logs**: `docker-compose logs` on target server

## 🔄 Post-Deployment Tasks

### Health Checks

```bash
# Run health check
ssh -i deploy/keys/production_key calejo@production-server.company.com 'cd /opt/calejo-control-adapter && ./scripts/health-check.sh'

# Check service status
ssh -i deploy/keys/production_key calejo@production-server.company.com 'cd /opt/calejo-control-adapter && docker-compose ps'
```

### Backup Setup

```bash
# Create initial backup
ssh -i deploy/keys/production_key calejo@production-server.company.com 'cd /opt/calejo-control-adapter && ./scripts/backup-full.sh'

# Schedule regular backups (add to crontab)
0 2 * * * /opt/calejo-control-adapter/scripts/backup-full.sh
```

### Monitoring Setup

```bash
# Check monitoring
ssh -i deploy/keys/production_key calejo@production-server.company.com 'cd /opt/calejo-control-adapter && ./validate-deployment.sh'
```

## 📋 Deployment Checklist

### Pre-Deployment
- [ ] SSH keys generated and deployed
- [ ] Configuration files created and tested
- [ ] Remote server prerequisites installed
- [ ] Backup strategy in place
- [ ] Deployment window scheduled

### During Deployment
- [ ] Dry run completed successfully
- [ ] Backup of existing deployment created
- [ ] Application files transferred
- [ ] Services started successfully
- [ ] Health checks passed

### Post-Deployment
- [ ] Application accessible via web interface
- [ ] API endpoints responding
- [ ] Monitoring configured
- [ ] Backup tested
- [ ] Documentation updated

## 🎯 Best Practices

### Deployment Strategy

- **Use blue-green deployment** for zero downtime
- **Test in staging** before production
- **Rollback plan** in place
- **Monitor during deployment**

### Configuration Management

- **Version control** for configuration
- **Environment-specific** configurations
- **Sensitive data** in environment variables
- **Regular backups** of configuration

### Security

- **Least privilege** principle
- **Regular security updates**
- **Access logging** and monitoring
- **Incident response** plan

---

**Deployment Status**: ✅ Production Ready
**Last Updated**: $(date)
**Version**: 1.0.0