Skip to content

Migration Guides

This page provides step-by-step migration guides for upgrading between major versions of Arctyk ITSM.

General Migration Process

When upgrading Arctyk ITSM between versions, follow these general steps:

  1. Backup your database - Always create a backup before upgrading
  2. Review the changelog - Check for breaking changes in the target version
  3. Update dependencies - Install new requirements from requirements.txt
  4. Run migrations - Apply database schema changes with python manage.py migrate
  5. Collect static files - Run python manage.py collectstatic
  6. Restart services - Restart your web server and Celery workers
  7. Test thoroughly - Verify critical functionality after upgrade

Migrating from 0.5.x to 0.6.0

What's New

  • Comments System: New Comment and CommentEditHistory tables for ticket discussions
  • SLA Fields: New response_target, resolution_target fields on Ticket model
  • Lifecycle Timestamps: New first_responded_at, resolved_at, closed_at timestamp fields
  • Enhanced Documentation: 3500+ lines of new component guides and developer documentation

Breaking Changes

None - Version 0.6.0 is fully backward compatible with 0.5.x.

Migration Steps

  1. Stop the application
docker-compose down  # Or systemctl stop arctyk-itsm
  1. Backup your database
# PostgreSQL
pg_dump arctyk > backup_0.6.0_$(date +%s).sql
  1. Update code
cd /path/to/arctyk
git pull origin main
  1. Install dependencies (if changed)
pip-sync requirements.txt
# or
docker-compose build
  1. Apply migrations
python manage.py migrate
# or
docker-compose exec web python src/manage.py migrate
  1. Collect static files
python manage.py collectstatic --noinput
# or
docker-compose exec web python src/manage.py collectstatic --noinput
  1. Restart services
docker-compose up -d
# or
systemctl restart arctyk-itsm
  1. Verify upgrade
  2. Visit dashboard and verify no 500 errors
  3. Create a test ticket and add a comment
  4. Verify SLA fields appear in admin
  5. Check that changelog entries are created for comments

No Code Changes Required

All new features are additive and don't require changes to existing custom code.

Documentation Updates

The documentation has been significantly expanded in 0.6.0:

  • Component Guides: See docs/components/ for UI component documentation
  • Testing Guide: See docs/developer-guide/testing.md for pytest patterns
  • SLA Guide: See docs/features/sla.md for SLA implementation details
  • Contributing: See CONTRIBUTING.md for commit message standards

Migrating from 0.4.x to 0.5.x

New Features

  • Workflow Audit Trail: Automatic changelog entries for status transitions
  • Inline Editing: AJAX-powered field editing on ticket detail view
  • Enhanced Workflow: Status history timeline display

Breaking Changes

None - Version 0.5.0 is fully backward compatible with 0.4.x.

Migration Steps

Similar to 0.5→0.6 migration above. No custom code changes required.

Migrating from 0.4.x to Future Versions

Migration guides will be added here as new major versions are released.

Migrating from 0.3.x to 0.4.x

Breaking Changes

  • Recurring Tickets Removed: The recurring ticket feature has been temporarily removed and will be reintroduced in a future version with improved architecture.
  • UI Overhaul: Custom CSS or JavaScript that relied on legacy UI elements may need updates.
  • Workflow Changes: Ticket status workflow now follows Jira-style category-based transitions.

Migration Steps

  1. Remove recurring ticket references: If you have any custom code or integrations that reference recurring tickets, remove or comment them out.

  2. Update static assets: The SCSS architecture has been reorganized. If you have custom styles, you may need to adjust import paths.

  3. Review workflow transitions: The ticket workflow system now uses category-based transitions. Review your custom workflows and update them to use the new WORKFLOW_TRANSITIONS pattern.

  4. Test AJAX forms: The Create and Update ticket forms now return JSON for AJAX requests. If you have custom JavaScript, ensure it handles JSON responses correctly.

Migrating from 0.2.x to 0.3.x

Migration Steps

This was an early development release. The recommendation is to start with 0.4.0 or later for production deployments.

  1. Update Django to the required version
  2. Run database migrations
  3. Update any custom templates that reference legacy models
  4. Test ticket creation and workflow transitions

Database Backup Best Practices

Before any migration:

# PostgreSQL backup
pg_dump -U arctyk_user arctyk_db > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore if needed
psql -U arctyk_user arctyk_db < backup_20250101_120000.sql

Rollback Procedure

If a migration fails or causes issues:

  1. Stop the application services
  2. Restore the database from backup
  3. Revert to the previous application version
  4. Restart services
  5. Investigate the migration issue before attempting again

Getting Help

If you encounter issues during migration: