Upgrade

Upgrading your Wraft installation

Upgrading your Wraft installation

Step-by-step guide to upgrade Wraft across different deployment methods

Docker

Update the images using the latest image from Wraft.

# Stop the current containers
docker-compose down
 
# Pull the latest images
docker-compose pull
 
# Start the updated containers
docker-compose up -d

After upgrading, run the database migrations:

# Access the backend container and run migrations
docker exec -it wraft-backend-1 sh -c 'mix ecto.migrate'
 
# Or if using the full container name
docker exec -it $(basename $(pwd))-backend-1 sh -c 'mix ecto.migrate'

Verify the Upgrade

  1. Check the application is running: docker-compose ps
  2. Visit your application URL to ensure it's working
  3. Check the logs for any errors: docker-compose logs -f

Kubernetes

This upgrade guide is applicable for Wraft Kubernetes deployments using Helm charts.

# Update helm repositories
helm repo update
 
# List your current installed version
helm list
 
# Show the latest version of charts that is going to be installed
helm search repo wraft
# If it is major version update, refer to the changelog before proceeding
helm upgrade wraft wraft/wraft -f <your-custom-values>.yaml

Post-Upgrade Steps

  1. Verify all pods are running: kubectl get pods
  2. Check application logs: kubectl logs -f deployment/wraft-backend
  3. Ensure database migrations completed successfully

Local

For local installations, follow these steps to upgrade Wraft:

Prerequisites

  • Backup your current installation
  • Ensure you have the latest dependencies installed

Upgrade Steps

# Navigate to your Wraft installation directory
cd /path/to/wraft
 
# Pull the latest changes
git pull origin main
 
# Install/update dependencies
mix deps.get
npm install --prefix assets
 
# Run database migrations
mix ecto.migrate
 
# Compile the application
mix compile
 
# Build frontend assets
npm run build --prefix assets
 
# Restart the application
# On Linux with systemd:
sudo systemctl restart wraft
 
# On macOS with launchd:
brew services restart wraft
 
# On Windows or other systems, restart your application manually

Verify the Upgrade

  1. Check service status (Linux): sudo systemctl status wraft
  2. Check service status (macOS): brew services list | grep wraft
  3. View application logs: Check your application's log files
  4. Test the application functionality

Backup Before Upgrade

Before performing any upgrade, it's recommended to create a backup:

Docker

# Backup database
docker exec -it wraft-postgres-1 pg_dump -U postgres wraft > backup_$(date +%Y%m%d_%H%M%S).sql
 
# Backup uploaded files (if using local storage)
tar -czf uploads_backup_$(date +%Y%m%d_%H%M%S).tar.gz ./uploads/

Kubernetes

# Backup database
kubectl exec -it deployment/wraft-postgres -- pg_dump -U postgres wraft > backup_$(date +%Y%m%d_%H%M%S).sql

Troubleshooting

Common Issues

  1. Database Migration Errors: Ensure your database is accessible and has sufficient permissions
  2. Asset Compilation Errors: Clear build cache and reinstall dependencies
  3. Service Won't Start: Check logs for configuration errors

Rollback Procedure

If the upgrade fails, you can rollback:

# Docker
docker-compose down
docker-compose up -d
 
# Kubernetes
helm rollback wraft <previous-revision>
 
# Local
git reset --hard HEAD~1
mix ecto.rollback
# Restart your application based on your setup

Version Compatibility

  • Check the changelog for breaking changes
  • Review the upgrade notes for your specific version
  • Test the upgrade in a staging environment first

Support

If you encounter issues during the upgrade process:

  1. Check the GitHub issues
  2. Review the documentation
  3. Join the community discussions

Previous

API Reference

On this page