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 guide refers to the existing machine as the source server and the newly launched machine as this server. Run the migration command on the new server; it does not need to be configured first.

The source must be a server or combined server + worker. The wizard selects one of those roles for this server. A worker-only machine contains temporary processing files rather than the complete API database, so it cannot be used as the migration source.

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 a new server from the latest Marketplace image.

  2. Do not run config-openshot-cloud on the new server. The migration copies compatible configuration from the source and asks you to confirm the new server’s role and URLs.

  3. Keep the source running and reachable from the new server over its private network address.

  4. Make sure the new server has enough disk space for the database dump, staged media, and a backup of its initial data.

  5. Create an SSH key on the new server if needed, and add its public key to the ubuntu account on the source server:

    # Run on the new server
ssh-keygen -t ed25519
cat ~/.ssh/id_ed25519.pub

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

Start the guided migration

Run the wizard on the new server:

sudo migrate-openshot-cloud

The command is available from any directory. The wizard asks for the source server’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
Safely move configuration, PostgreSQL data, and media to this server
================================================================

Source server private IP or hostname: 10.0.1.24

  Working directory:   /var/lib/openshot-cloud/migrations/20260808-195322

Connect to source server
------------------------
  Connecting to ubuntu@10.0.1.24 ...
✓ SSH connection established

Source inventory
----------------
  Operating system:    Ubuntu 18.04.6 LTS
  OpenShot version:    2.3.0
  Role:                both
  Cloud provider:      AWS (diagnostic)
  PostgreSQL:          10.23
  Settings:            /home/ubuntu/api/api/settings/production-AWS.py
  Database:            openshot_cloud

Transfer database
-----------------
  Creating a PostgreSQL dump on the source server ...

Transfer media
--------------
  Synchronizing files and exports (safe to resume) ...

Configuration plan
------------------
  Destination: api/settings/production-AWS.py
  Role:                both (copied from source)
  CLOUD_PASSWORD:      <redacted>
  AWS_ACCESS_KEY_ID:   <redacted>
  AWS_REGION_NAME:     us-east-1

Validate staged migration
-------------------------
✓ Database validation passed: users=8 projects=3 files=4 clips=3 effects=0 exports=0
✓ Media validation passed: media_references=4 local=4 cloud_backed=0 missing=0

Ready to update this server
---------------------------
  Temporary database:  openshot_migration_20260808_195322
  Staged media:        /var/lib/openshot-cloud/migrations/20260808-195322/video
Type MIGRATE to replace this server's database and media: MIGRATE

Migration complete
------------------
✓ This server was updated successfully

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

Validation and promotion

The source server operates normally throughout staging. The wizard restores its database into a temporary database on this server, applies current migrations, and checks media references. It does not run integration tests before promotion because both servers may still share an export queue. This server’s active database and media are not replaced until validation succeeds and you type MIGRATE (case-insensitive).

During promotion, this server’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 migrate-openshot-cloud --resume <migration-id>

Use --no-promote to stage and validate without updating this server.

See every supported migration option at any time with:

migrate-openshot-cloud --help

After promotion, give this server a queue that is not shared with the source. For AWS and Azure, update only the queue setting and restart OpenShot services with one command:

config-openshot-cloud --queue-name NEW-QUEUE-NAME

To change only this server’s canonical public API origin and restart the services for its configured role, run:

config-openshot-cloud --http-host https://api.example.com

The URL must be a complete origin (for example, https://api.example.com), without a path, query string, or fragment. To see both focused configuration options and examples, run:

config-openshot-cloud --help

Then run the API integration tests from /home/ubuntu/api:

python3 manage.py runtests

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 the new server

For a manual migration, run config-openshot-cloud on the new server first. Configure its cloud credentials, queue, role, and URLs deliberately. Avoid sharing a queue between the source and new servers while both are processing jobs. This manual-only step is not needed by the guided migration.

Copy media

From the new server, pull the authoritative media directories from the source. Replace SOURCE-SERVER with its private address:

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

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

Export and import the database

As a compatibility fallback, create a Django data export on the source server:

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

On the new server, 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 the new server’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.