Skip to main content

Rollback Process - Admin Panel

This guide provides step-by-step instructions for rolling back the Admin Panel to a previous version when issues are discovered in production or staging environments.

Prerequisites​

Before starting the rollback process, ensure you have:

  • Access to the repository and GitHub Actions
  • Appropriate permissions for the target environment
  • Knowledge of the version to rollback to
  • Understanding of the issues that require rollback
warning

Rollback should only be performed when necessary. Consider deploying a hotfix first if the issues can be resolved quickly.

Rollback Process​

Follow these steps to rollback the Admin Panel to a previous version:

Step 1: Identify Target Version​

  1. Review Version History

    • Identify the last known stable version
    • Verify the version number (e.g., 1.0.0, 1.2.3)
    • Confirm the version exists in the container registry

  2. Verify Version Compatibility

    • Ensure the target version is compatible with the current environment
    • Check for any database schema requirements
    • Verify API compatibility if applicable

Step 2: Navigate to GitHub Actions​

  1. Access Repository

    • Go to the repository on GitHub
    • Ensure you're viewing the correct repository and branch

  2. Open Actions Tab

    • Click on the Actions tab in the repository navigation
    • Locate the Prod Pipeline workflow in the workflow list

Step 3: Initiate Rollback Workflow​

  1. Run Workflow

    • Click on Prod Pipeline to open the workflow
    • Click the Run workflow dropdown button (located on the right side)
    • Select Run workflow from the dropdown

  2. Configure Rollback Parameters

    • Version: Enter the version number you want to rollback to (e.g., 1.0.0)
      • Use semantic versioning format: x.y.z
      • Ensure the version exists in the container registry
    • Branch: Select the appropriate branch (usually main for production)

  3. Confirm Rollback

    • Review all parameters carefully
    • Click Run workflow to initiate the rollback process
Version Format

The version should follow semantic versioning (SemVer) format:

  • Example: 1.0.0, 1.2.3, 2.0.1
  • Do not include prefixes like v or version

Step 4: Monitor Rollback Process​

  1. Track Workflow Execution

    • Monitor the workflow run in the Actions tab
    • Watch for any errors or warnings during execution
    • Check each step of the deployment pipeline

  2. Verify Deployment Steps

    • Container build (if applicable)
    • Image push to registry
    • Container deployment
    • Health checks

Step 5: Verify Rollback Success​

After the workflow completes, verify the rollback was successful:

  1. Check Service Status

    • Verify the Admin Panel is accessible
    • Check that the service is running correctly
    • Monitor application logs for errors

  2. Test Critical Functionality

    • Test key features and workflows
    • Verify user authentication and authorization
    • Check data integrity and consistency

  3. Monitor System Health

    • Check application metrics and performance
    • Review error logs for any issues
    • Monitor resource usage (CPU, memory, disk)
Verification Checklist
  • Admin Panel is accessible via URL
  • User login works correctly
  • Core features are functional
  • No critical errors in logs
  • Performance is within acceptable range

Post-Rollback Actions​

After a successful rollback:

  1. Document the Rollback

    • Record the reason for rollback
    • Document the version rolled back from and to
    • Note any issues encountered during rollback

  2. Communicate with Team

    • Notify the team about the rollback
    • Share the reason and target version
    • Update relevant documentation

  3. Investigate Root Cause

    • Analyze why the deployment caused issues
    • Review code changes between versions
    • Plan fixes for the problematic version

  4. Plan Forward

    • Decide on next steps (hotfix, re-deployment, etc.)
    • Schedule fixes for the rolled-back version
    • Update deployment procedures if needed

Troubleshooting​

Common Issues​

Workflow fails to start

  • Verify you have permissions to run workflows
  • Check that the workflow file exists and is valid
  • Ensure you're on the correct branch

Version not found

  • Verify the version exists in the container registry
  • Check the version format matches exactly
  • Ensure the version was previously deployed

Rollback deployment fails

  • Check workflow logs for specific error messages
  • Verify container registry access and permissions
  • Ensure all required secrets and environment variables are configured
  • Check for resource constraints (disk space, memory)

Admin Panel not accessible after rollback

  • Verify the service container is running: docker ps
  • Check service logs: docker logs <container-name>
  • Verify environment variables are correctly set
  • Ensure firewall rules allow traffic on the configured ports
  • Check DNS and routing configuration

Functionality issues after rollback

  • Verify database schema compatibility
  • Check for missing environment variables
  • Review application logs for errors
  • Verify API compatibility if Admin Panel depends on API services

Performance issues after rollback

  • Check resource usage (CPU, memory, disk)
  • Review application logs for performance-related errors
  • Verify database connection pool settings
  • Check for memory leaks or resource exhaustion

Best Practices​

  1. Maintain Version History - Keep detailed records of all deployed versions
  2. Test Rollback Procedures - Periodically test rollback in staging environment
  3. Document Issues - Document why rollback was necessary for future reference
  4. Communicate Early - Notify team before performing rollback
  5. Verify Thoroughly - Test all critical functionality after rollback
  6. Monitor Closely - Watch system metrics and logs after rollback
  7. Plan Hotfixes - Have a plan to fix issues in the rolled-back version