8.7 KiB

Raw Blame History

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:

# 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:

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

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

3. Deploy

# 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`)

# 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`)

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

# 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

# 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

# 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

# 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

# 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:

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

🔄 Deployment Process

The deployment script performs the following steps:

Configuration Validation
- Loads environment configuration
- Validates SSH key and connection details
- Checks remote prerequisites
Remote Setup
- Creates necessary directories
- Backs up existing deployment (if any)
- Transfers application files
Application Deployment
- Sets up remote configuration
- Builds Docker images
- Starts services
- Waits for services to be ready
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

SSH Connection Failed

# Check key permissions
chmod 600 deploy/keys/production_key

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

Permission Denied

# Ensure user has sudo access
ssh -i deploy/keys/production_key calejo@production-server.company.com 'sudo -v'

Docker Not Installed

# Check Docker installation
ssh -i deploy/keys/production_key calejo@production-server.company.com 'docker --version'

Port Already in Use

# 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:

./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

# 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

# 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

# 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

8.7 KiB Raw Blame History