> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Updates

> System updates and version management for Runlayer

## Hosted vs. Self-Hosted

<Info>
  This page covers **self-hosted** deployments, where you run Runlayer on your own infrastructure via [Terraform or Helm](/deployment/overview). On **Runlayer-hosted** deployments, Runlayer operates the infrastructure and applies updates for you — no action is required on your side. Release notes for every version are published in the [changelog](/changelog); for hosted update timing and policies, contact [support@runlayer.com](mailto:support@runlayer.com).
</Info>

## Update Process

Runlayer updates are **manual** and controlled through Terraform. There is no automated update system - you have full control over when and how updates are applied.

## How Updates Work

### Container Images

Runlayer uses **automated semantic versioning** with multiple tag options:

```hcl theme={null}
# Available image tag formats
image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:latest"         # Always latest
image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:v1.2.3"         # Stable version
image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:20241213-152430" # Timestamp
```

**Available Tag Types:**

* **`latest`**: Always points to the most recent release
* **`v1.2.3`**: Semantic version tags for stable deployments
* **`20241213-152430`**: Timestamp-based tags for specific builds
* **`v1.2.3-20241213-152430-a1b2c3d4`**: Full build traceability (includes commit SHA)

### Update Methods

<Tabs>
  <Tab title="Rolling Updates (Recommended)">
    **Standard update process with zero downtime:**

    ```bash theme={null}
    cd infra

    # 1. Check for infrastructure changes
    terraform plan -var-file="production.tfvars"

    # 2. Apply updates (triggers ECS service updates)
    terraform apply -var-file="production.tfvars"

    # 3. Monitor deployment
    aws ecs describe-services --cluster anysource-production
    ```

    **What happens:**

    * ECS pulls latest container images from ECR
    * Rolling deployment replaces containers one by one
    * Health checks ensure new containers are healthy before removing old ones
    * Zero downtime for users
  </Tab>

  <Tab title="Forced Updates">
    **Force ECS to pull new images even if task definition hasn't changed:**

    ```bash theme={null}
    # Force service update without terraform changes
    aws ecs update-service \
      --cluster anysource-production \
      --service backend-service \
      --force-new-deployment

    aws ecs update-service \
      --cluster anysource-production \
      --service frontend-service \
      --force-new-deployment
    ```

    **When to use:**

    * New images pushed to ECR with `:latest` tag
    * No terraform configuration changes
    * Emergency updates
  </Tab>
</Tabs>

## Version Management Strategies

### Automated Versioning System

Runlayer uses **automated semantic versioning** based on conventional commits:

<Info>
  **How versions are determined:**

  * **Patch bump** (`v1.2.3` → `v1.2.4`): Bug fixes, documentation updates
  * **Minor bump** (`v1.2.3` → `v1.3.0`): New features (`feat:` commits)
  * **Major bump** (`v1.2.3` → `v2.0.0`): Breaking changes (`feat!:` or `BREAKING CHANGE:`)
</Info>

### Deployment Strategies

<Accordion title="Option 1: Use Latest (Auto-Updates)">
  **Always get the newest version:**

  ```hcl theme={null}
  # Terraform configuration
  image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:latest"
  ```

  **Benefits:**

  * Automatic security patches
  * Latest features and improvements
  * Minimal maintenance overhead

  **Considerations:**

  * Updates happen when you run `terraform apply`
  * May include breaking changes in major versions
</Accordion>

<Accordion title="Option 2: Pin to Semantic Versions">
  **Use stable version tags for production:**

  ```hcl theme={null}
  # Pin to specific major.minor version
  image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:v1.2.3"

  # Or pin to major version (gets patch updates)
  image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:v1.2"
  ```

  **Benefits:**

  * Predictable deployments
  * Control over when breaking changes are applied
  * Easy rollbacks by changing version tags

  **Update process:**

  ```bash theme={null}
  # Update to newer version
  terraform apply -var="backend_version=v1.3.0"
  ```
</Accordion>

<Accordion title="Option 3: Staged Update Strategy">
  **Test versions before production deployment:**

  ```hcl theme={null}
  # Staging: Use latest for testing
  image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:latest"

  # Production: Pin to tested version
  image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:v1.2.3"
  ```

  **Workflow:**

  1. New version deploys to staging automatically
  2. Test thoroughly in staging environment
  3. Update production to use tested version tag
  4. Rollback easily if issues arise
</Accordion>

### Finding Available Versions

<Tabs>
  <Tab title="AWS CLI">
    **List all available versions:**

    ```bash theme={null}
    # List backend versions
    aws ecr describe-images \
      --repository-name backend-production \
      --registry-id 170974506510 \
      --region us-east-1 \
      --query 'imageDetails[*].imageTags' \
      --output table

    # List frontend versions
    aws ecr describe-images \
      --repository-name frontend-production \
      --registry-id 170974506510 \
      --region us-east-1 \
      --query 'imageDetails[*].imageTags' \
      --output table
    ```
  </Tab>

  <Tab title="GitHub Releases">
    **Check the GitHub repository:**

    * Review the [Runlayer changelog](/changelog) for release notes
    * Each release corresponds to a semantic version tag
    * Release notes include changelog and breaking changes
  </Tab>
</Tabs>

## Update Monitoring

### Health Checks During Updates

The ECS service configuration includes automatic health monitoring:

```hcl theme={null}
# Health check configuration
health_check_path = "/api/v1/utils/health-check/"  # Backend
health_check_path = "/"                            # Frontend
```

**Monitor deployment progress:**

```bash theme={null}
# Watch service status
aws ecs describe-services \
  --cluster anysource-production \
  --services backend-service frontend-service

# Check target group health
aws elbv2 describe-target-health \
  --target-group-arn <target-group-arn>

# View application logs
aws logs tail /aws/ecs/backend-logs-production --follow
```

### Rollback Procedures

<Steps>
  <Step title="Version Rollback (Recommended)">
    **Rollback to a previous semantic version:**

    ```hcl theme={null}
    # Update your terraform configuration
    image = "170974506510.dkr.ecr.us-east-1.amazonaws.com/backend-production:v1.2.2"  # Previous version
    ```

    ```bash theme={null}
    # Apply the change
    terraform apply -var-file="production.tfvars"
    ```

    **Benefits:**

    * Clean rollback to known stable version
    * Maintains deployment history
    * Easy to communicate to team
  </Step>

  <Step title="Emergency Service Rollback">
    **If immediate rollback is needed:**

    ```bash theme={null}
    # Stop the current deployment
    aws ecs update-service \
      --cluster anysource-production \
      --service backend-service \
      --desired-count 0

    # Scale back up (will use previous task definition)
    aws ecs update-service \
      --cluster anysource-production \
      --service backend-service \
      --desired-count 2
    ```

    **Then update to stable version:**

    ```bash theme={null}
    terraform apply -var="backend_version=v1.2.2"
    ```
  </Step>
</Steps>

## Database Migrations

Database updates require special handling:

### Manual Migration Process

```bash theme={null}
# 1. Backup database before migrations
aws rds create-db-cluster-snapshot \
  --db-cluster-identifier anysource-production \
  --db-cluster-snapshot-identifier backup-before-update-$(date +%Y%m%d)

# 2. Run migrations (usually handled by application startup)
# Backend container automatically runs migrations on startup

# 3. Verify migration success
curl https://your-domain.com/api/v1/utils/health-check/
```

### Migration Safety

* **Automated backups**: Aurora automatically backs up every 7 days (configurable)
* **Point-in-time recovery**: Can restore to any point within backup retention period
* **Cluster snapshots**: Manual snapshots before major updates

## Security Updates

### Critical Security Patches

<Steps>
  <Step title="Emergency Updates">
    For critical security issues:

    ```bash theme={null}
    # 1. Build and push patched images immediately
    docker build -t backend:security-patch .
    docker tag backend:security-patch ${ECR_URL}:latest
    docker push ${ECR_URL}:latest

    # 2. Force immediate deployment
    aws ecs update-service \
      --cluster anysource-production \
      --service backend-service \
      --force-new-deployment
    ```
  </Step>

  <Step title="Infrastructure Patches">
    **AWS-managed services are automatically patched:**

    * **RDS Aurora**: Automatic security patches during maintenance windows
    * **ECS Fargate**: AWS manages underlying infrastructure
    * **ALB/VPC**: AWS-managed security updates

    **Configure maintenance windows:**

    ```hcl theme={null}
    preferred_maintenance_window = "sun:05:00-sun:06:00"
    ```
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Before Updates" icon="list-check">
    * Review release notes and breaking changes
    * Backup database with manual snapshot
    * Test in staging environment first
    * Schedule during low-traffic periods
    * Have rollback plan ready
  </Card>

  <Card title="During Updates" icon="eye">
    * Monitor health check endpoints
    * Watch ECS service status
    * Check application logs for errors
    * Verify target group health
    * Test critical functionality
  </Card>

  <Card title="After Updates" icon="check-circle">
    * Verify all services are healthy
    * Test key user workflows
    * Monitor error rates and performance
    * Clean up old task definitions
    * Document any issues encountered
  </Card>

  <Card title="Emergency Procedures" icon="exclamation-triangle">
    * Know how to quickly rollback
    * Have monitoring dashboards ready
    * Keep communication channels open
    * Document incident response steps
    * Practice rollback procedures
  </Card>
</CardGroup>

## Troubleshooting Updates

<Accordion title="Service Won't Start After Update">
  **Common causes and solutions:**

  ```bash theme={null}
  # Check task definition and logs
  aws ecs describe-task-definition --task-definition anysource-backend-production
  aws logs tail /aws/ecs/backend-logs-production

  # Common issues:
  # - Environment variable changes
  # - Database migration failures
  # - Container startup errors
  # - Health check failures
  ```
</Accordion>

<Accordion title="Deployment Stuck or Slow">
  **ECS deployment issues:**

  ```bash theme={null}
  # Check service events
  aws ecs describe-services --cluster anysource-production --services backend-service

  # Force stop problematic tasks
  aws ecs stop-task --cluster anysource-production --task <task-arn>

  # Restart deployment
  aws ecs update-service --cluster anysource-production --service backend-service --force-new-deployment
  ```
</Accordion>

<Accordion title="Database Connection Issues">
  **Database connectivity problems:**

  ```bash theme={null}
  # Check RDS status
  aws rds describe-db-clusters --db-cluster-identifier anysource-production

  # Check security groups
  aws ec2 describe-security-groups --group-ids <db-security-group-id>

  # Test connection from ECS task
  aws ecs execute-command --cluster anysource-production --task <task-arn> --interactive --command "/bin/bash"
  ```
</Accordion>

Remember: **You have full control over when updates happen.** The system will not update automatically - all updates require manual terraform commands.