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

# Upgrade Guide

> Keep your self-hosted DeployStack instance up-to-date with the latest features and security patches.

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

## General Guidelines

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

### Backup Your Data

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

<Steps>
  <Step title="Stop DeployStack Services">
    ```bash theme={null}
    docker-compose down
    ```
  </Step>

  <Step title="Pull Latest Images">
    ```bash theme={null}
    docker-compose pull
    ```

    This downloads the latest versions of both frontend and backend images.
  </Step>

  <Step title="Start Updated Services">
    ```bash theme={null}
    docker-compose up -d
    ```
  </Step>

  <Step title="Verify Upgrade">
    Check that services are running properly:

    ```bash theme={null}
    # Check service status
    docker-compose ps

    # Check logs for any errors
    docker-compose logs

    # Access the web interface to verify functionality
    ```
  </Step>
</Steps>

## Upgrading to Specific Versions

To upgrade to a specific version instead of the latest:

### Method 1: Update Docker Compose File

1. **Edit your `docker-compose.yml`**:

```yaml theme={null}
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
```

2. **Apply the changes**:

```bash theme={null}
docker-compose down
docker-compose up -d
```

### Method 2: Use Environment Variables

1. **Add version to your `.env` file**:

```bash theme={null}
# Add to .env
DEPLOYSTACK_VERSION=v1.2.0
```

2. **Update docker-compose.yml to use the variable**:

```yaml theme={null}
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.

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

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

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

### Sequential Upgrade Process

1. **Identify your current version**:

```bash theme={null}
# Check current version in logs
docker-compose logs backend | grep -i version

# Or check the web interface footer
```

2. **Plan your upgrade path**:
   * v0.8.x → v0.9.x → v1.0.x → v1.1.x → v1.2.x

3. **Upgrade step by step**:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

<Steps>
  <Step title="Stop Current Services">
    ```bash theme={null}
    docker-compose down
    ```
  </Step>

  <Step title="Restore Previous Configuration">
    ```bash theme={null}
    # Restore from backup
    cp backups/BACKUP_DATE/.env .
    cp backups/BACKUP_DATE/docker-compose.yml .
    ```
  </Step>

  <Step title="Restore Data (if needed)">
    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Start Previous Version">
    ```bash theme={null}
    docker-compose up -d
    ```
  </Step>
</Steps>

## Automated Upgrade Scripts

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

```bash theme={null}
#!/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:

```bash theme={null}
chmod +x upgrade-deploystack.sh
./upgrade-deploystack.sh
```

## Monitoring Upgrades

### Health Checks

After upgrading, verify system health:

```bash theme={null}
# 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:

```bash theme={null}
# Monitor container resources
docker stats --no-stream

# Check disk usage
df -h
docker system df
```

## Getting Help

If you encounter issues during upgrades:

1. **Check Release Notes**: Review the specific version's release notes for known issues
2. **Search Issues**: Look for similar problems in [GitHub Issues](https://github.com/deploystackio/deploystack/issues)
3. **Community Support**: Ask for help in our [Discord](https://discord.gg/UjFWwByB)
4. **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](https://github.com/deploystackio/deploystack/releases) to get notified of new versions and security updates.