Upgrade Guide - DeployStack - Enterprise Control Plane for MCP

Keep your self-hosted DeployStack instance secure and up-to-date with the latest features, bug fixes, and security patches.

General Guidelines

Always backup your data before starting the upgrade process. This ensures you can restore your instance if anything goes wrong during the upgrade.

Backup Your Data

Before upgrading, create a complete backup of your DeployStack data:

# Create backup directory with timestamp
mkdir -p backups/$(date +%Y%m%d_%H%M%S)

# Backup Docker volume
docker run --rm \
  -v deploystack_backend_persistent:/data \
  -v $(pwd)/backups/$(date +%Y%m%d_%H%M%S):/backup \
  alpine tar czf /backup/backend_persistent.tar.gz -C /data .

# Backup your configuration
cp .env backups/$(date +%Y%m%d_%H%M%S)/
cp docker-compose.yml backups/$(date +%Y%m%d_%H%M%S)/

Restore from Backup

If you need to restore from a backup:

# Stop services
docker-compose down

# Remove existing volume (CAUTION: This will delete current data)
docker volume rm deploystack_backend_persistent

# Restore from backup
docker run --rm \
  -v deploystack_backend_persistent:/data \
  -v $(pwd)/backups/BACKUP_DATE:/backup \
  alpine tar xzf /backup/backend_persistent.tar.gz -C /data

# Restore configuration
cp backups/BACKUP_DATE/.env .
cp backups/BACKUP_DATE/docker-compose.yml .

# Start services
docker-compose up -d

Standard Upgrade Process

For most upgrades, follow this simple process:

Stop DeployStack Services

docker-compose down

Pull Latest Images

docker-compose pull

This downloads the latest versions of both frontend and backend images.

Start Updated Services

docker-compose up -d

Verify Upgrade

Check that services are running properly:

# Check service status
docker-compose ps

# Check logs for any errors
docker-compose logs

# Access the web interface to verify functionality

Upgrading to Specific Versions

To upgrade to a specific version instead of the latest:

Method 1: Update Docker Compose File

Edit your docker-compose.yml:

services:
  backend:
    image: deploystack/backend:v1.2.0  # Specify version
    # ... rest of configuration
    
  frontend:
    image: deploystack/frontend:v1.2.0  # Specify version
    # ... rest of configuration

Apply the changes:

docker-compose down
docker-compose up -d

Method 2: Use Environment Variables

Add version to your .env file:

# Add to .env
DEPLOYSTACK_VERSION=v1.2.0

Update docker-compose.yml to use the variable:

services:
  backend:
    image: deploystack/backend:${DEPLOYSTACK_VERSION:-latest}
    # ... rest of configuration
    
  frontend:
    image: deploystack/frontend:${DEPLOYSTACK_VERSION:-latest}
    # ... rest of configuration

Version-Specific Upgrade Notes

v1.0.0 and Later

Starting from v1.0.0, DeployStack follows semantic versioning and includes automatic database migrations.

No manual intervention required for standard upgrades. The application handles database migrations automatically on startup.

Pre-v1.0.0 Versions

For versions before v1.0.0, some manual steps may be required. Check the specific release notes for your version.

Upgrading Across Multiple Versions

When upgrading across multiple major versions (e.g., from v0.8.x to v1.2.x), upgrade sequentially through each major version to ensure proper data migration.

Sequential Upgrade Process

Identify your current version:

# Check current version in logs
docker-compose logs backend | grep -i version

# Or check the web interface footer

Plan your upgrade path:
- v0.8.x → v0.9.x → v1.0.x → v1.1.x → v1.2.x
Upgrade step by step:

# Example: Upgrading from v0.8.5 to v1.2.0

# Step 1: Upgrade to v0.9.0
docker-compose down
# Update images to v0.9.0 in docker-compose.yml
docker-compose up -d
# Verify functionality

# Step 2: Upgrade to v1.0.0
docker-compose down
# Update images to v1.0.0
docker-compose up -d
# Verify functionality

# Continue until reaching target version

Configuration Updates

Some upgrades may require configuration changes:

Environment Variables

Check release notes for new or changed environment variables:

# Download latest .env.example
curl -o .env.example https://raw.githubusercontent.com/deploystackio/deploystack/main/.env.example

# Compare with your current .env
diff .env .env.example

Docker Compose Changes

Compare your docker-compose.yml with the latest version:

# Download latest docker-compose.yml
curl -o docker-compose.yml.new https://raw.githubusercontent.com/deploystackio/deploystack/main/docker-compose.yml

# Compare files
diff docker-compose.yml docker-compose.yml.new

Rollback Procedure

If an upgrade fails or causes issues:

Stop Current Services

docker-compose down

Restore Previous Configuration

# Restore from backup
cp backups/BACKUP_DATE/.env .
cp backups/BACKUP_DATE/docker-compose.yml .

Restore Data (if needed)

# Only if data corruption occurred
docker volume rm deploystack_backend_persistent

# Restore volume from backup
docker run --rm \
  -v deploystack_backend_persistent:/data \
  -v $(pwd)/backups/BACKUP_DATE:/backup \
  alpine tar xzf /backup/backend_persistent.tar.gz -C /data

Start Previous Version

docker-compose up -d

Automated Upgrade Scripts

For regular maintenance, you can create an automated upgrade script:

#!/bin/bash
# upgrade-deploystack.sh

set -e

echo "Starting DeployStack upgrade..."

# Create backup
echo "Creating backup..."
BACKUP_DIR="backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup volume
docker run --rm \
  -v deploystack_backend_persistent:/data \
  -v "$(pwd)/$BACKUP_DIR":/backup \
  alpine tar czf /backup/backend_persistent.tar.gz -C /data .

# Backup configuration
cp .env "$BACKUP_DIR/"
cp docker-compose.yml "$BACKUP_DIR/"

echo "Backup created in $BACKUP_DIR"

# Perform upgrade
echo "Stopping services..."
docker-compose down

echo "Pulling latest images..."
docker-compose pull

echo "Starting updated services..."
docker-compose up -d

echo "Waiting for services to start..."
sleep 30

# Verify upgrade
if docker-compose ps | grep -q "Up"; then
    echo "✅ Upgrade completed successfully!"
    echo "DeployStack is available at: http://localhost:8080"
else
    echo "❌ Upgrade failed. Check logs with: docker-compose logs"
    exit 1
fi

Make it executable and run:

chmod +x upgrade-deploystack.sh
./upgrade-deploystack.sh

Monitoring Upgrades

Health Checks

After upgrading, verify system health:

# Check service health
curl -f http://localhost:3000/ || echo "Backend health check failed"
curl -f http://localhost:8080 || echo "Frontend health check failed"

# Check logs for errors
docker-compose logs --tail=50 | grep -i error

Performance Monitoring

Monitor resource usage after upgrades:

# Monitor container resources
docker stats --no-stream

# Check disk usage
df -h
docker system df

Getting Help

If you encounter issues during upgrades:

Check Release Notes: Review the specific version’s release notes for known issues
Search Issues: Look for similar problems in GitHub Issues
Community Support: Ask for help in our Discord
Create Issue: Report bugs with detailed logs and system information

Best Practices

Regular Updates: Update monthly or when security patches are released
Test Environment: Test upgrades in a staging environment first
Maintenance Windows: Schedule upgrades during low-usage periods
Documentation: Keep notes of any custom configurations or modifications
Monitoring: Set up alerts for service failures or performance issues

Stay Updated: Subscribe to our releases to get notified of new versions and security updates.

​General Guidelines

​Backup Your Data

​Restore from Backup

​Standard Upgrade Process

​Upgrading to Specific Versions

​Method 1: Update Docker Compose File

​Method 2: Use Environment Variables

​Version-Specific Upgrade Notes

​v1.0.0 and Later

​Pre-v1.0.0 Versions

​Upgrading Across Multiple Versions

​Sequential Upgrade Process

​Configuration Updates

​Environment Variables

​Docker Compose Changes

​Rollback Procedure

​Automated Upgrade Scripts

​Monitoring Upgrades

​Health Checks

​Performance Monitoring

​Getting Help

​Best Practices

General Guidelines

Backup Your Data

Restore from Backup

Standard Upgrade Process

Upgrading to Specific Versions

Method 1: Update Docker Compose File

Method 2: Use Environment Variables

Version-Specific Upgrade Notes

v1.0.0 and Later

Pre-v1.0.0 Versions

Upgrading Across Multiple Versions

Sequential Upgrade Process

Configuration Updates

Environment Variables

Docker Compose Changes

Rollback Procedure

Automated Upgrade Scripts

Monitoring Upgrades

Health Checks

Performance Monitoring

Getting Help

Best Practices