Upgrade | Migrate

To upgrade OpenShot Cloud API, launch a new instance from the latest Marketplace image and migrate your existing data to it. The guided migrate-openshot-cloud utility walks you through the process one step at a time. It safely moves data from the old server, supports historical OpenShot releases, checks the migrated system before it goes live, and leaves the old server unchanged.

See Release Notes when deciding whether a new release contains an upgrade you need.

Migration terminology

The migration wizard uses two short names throughout the process:

  • Instance A is the old OpenShot Cloud server containing your existing database, videos, exports, and configuration.

  • Instance B is the newly launched and configured OpenShot Cloud server. Run the migration command from this instance.

Both instances must be a server or combined server + worker. A worker-only instance contains temporary processing files rather than the complete API database, so it cannot be used for this migration.

What gets migrated

The guided migration handles the related pieces together:

  • your users, projects, and editing data from the OpenShot database;

  • uploaded files and completed exports in video/files and video/output;

  • EFS-style symbolic links by copying the linked directory contents;

  • compatible, configured API and cloud settings;

  • the public and internal API URLs, after confirmation;

  • optional server or server + worker role changes, including the corresponding Apache and Supervisor configuration.

Secrets are never printed in full. The preview reports whether credentials are configured while showing useful non-secret values such as usernames, regions, queues, buckets, paths, and URLs.

Before you begin

  1. Launch instance B from the latest Marketplace image.

  2. Configure B normally with config-openshot-cloud. Its current role is preserved by default during migration.

  3. Keep A running and reachable from B over its private network address.

  4. Make sure B has enough disk space for the database dump, staged media, and a backup of B’s initial data.

  5. Create an SSH key on B if needed, and add its public key to the ubuntu account on A:

    # Run on instance B
ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub

    Append the displayed public key to ~ubuntu/.ssh/authorized_keys on A. The wizard will print the key and retry instructions if its first connection attempt fails.

Start the guided migration

Run the wizard on instance B:

cd /home/ubuntu/api
sudo utilities/migrate-openshot-cloud

The wizard asks for A’s private IP address, verifies SSH, discovers the old layout, and explains each major operation before running it. A typical session looks like this:

OpenShot Cloud API Migration
Instance A private IP or hostname: 10.0.1.24

Connecting to ubuntu@10.0.1.24 ... connected

Source: Ubuntu 18.04.6 LTS
OpenShot: 2.3.0
Role: both
PostgreSQL: 10.23
Settings: /home/ubuntu/api/api/settings/production-AWS.py
Database: openshot_cloud

Creating a PostgreSQL dump on instance A ... done
Synchronizing video/files ... done
Synchronizing video/output ... done
Restoring temporary database ... done
Applying current Django migrations ... done
Integration tests passed.

Configuration plan for B:
  Role: both (preserved from B)
  CLOUD_USERNAME: cloud-admin
  CLOUD_PASSWORD: <redacted>
  AWS_ACCESS_KEY_ID: <redacted>
  AWS_SECRET_ACCESS_KEY: <redacted>
  AWS_REGION_NAME: us-east-1
  CLOUD_HTTP_HOST: https://video.example.com

READY TO PROMOTE
Type MIGRATE to replace B's default database and media: MIGRATE

Migration complete.

The exact output varies by OpenShot release, cloud provider, media layout, and selected settings. Provider-specific values that do not apply to B are listed and skipped.

Validation and promotion

A performs normally throughout staging. The wizard restores its database into a temporary database on B, applies current migrations, checks media references, and runs the API integration suite there. B’s active database and media are not replaced until validation succeeds and you type MIGRATE.

During promotion, B’s original database, media, and settings are backed up in:

/var/lib/openshot-cloud/migrations/<migration-id>/

If discovery, transfer, restore, or validation fails, the wizard stops and prints the location of migration.log. Interrupted media transfers can be continued without starting over:

sudo utilities/migrate-openshot-cloud --resume <migration-id>

Use --no-promote to stage and validate without replacing B. Use --skip-integration-tests only when the isolated API and worker tests cannot run in the destination environment.

Manual migration

Use this fallback only when the guided migration cannot handle a customized or damaged installation and its error message identifies work that must be done manually. Take independent backups before continuing. Manual migration does not provide the wizard’s temporary restore, compatibility checks, resumable state, or automatic rollback.

Configure instance B

Run config-openshot-cloud on B first. Configure its cloud credentials, queue, role, and URLs deliberately. Avoid sharing a queue between A and B while both are processing jobs.

Copy media

From B, pull the authoritative media directories from A. Replace INSTANCE-A with its private address:

cd /home/ubuntu/api
rsync -az --partial --info=progress2 \
  ubuntu@INSTANCE-A:/home/ubuntu/api/video/files/ video/files/
rsync -az --partial --info=progress2 \
  ubuntu@INSTANCE-A:/home/ubuntu/api/video/output/ video/output/
sudo chown -R ubuntu:www-data video/files video/output

If A uses symbolic links to mounted storage, verify and copy the linked contents rather than recreating an absolute link that is invalid on B.

Export and import the database

As a compatibility fallback, create a Django data export on A:

cd /home/ubuntu/api
python3 manage.py dumpdata --exclude contenttypes > backup.json
rsync -az backup.json ubuntu@INSTANCE-B:/home/ubuntu/api/

On B, adapt older JSON schemas and load the result:

cd /home/ubuntu/api/utilities
python3 migrate_backup_json.py
cd /home/ubuntu/api
python3 manage.py loaddata -e authtoken.Token backup-fixed.json

For PostgreSQL-level backup and restore, use the commands appropriate for the exact PostgreSQL versions involved. Restore into a temporary database and test it before replacing B’s configured database.

Support

If the guided utility stops and the manual path is unclear, contact cloud-support@openshot.org with the OpenShot versions, the final error, and the redacted migration log. OpenShot Studios can also provide a quote for assisted migration or patching.