.. Copyright (c) 2008-2016 OpenShot Studios, LLC
 (http://www.openshotstudios.com). This file is part of
 OpenShot Video Editor (http://www.openshot.org), an open-source project
 dedicated to delivering high quality video editing and animation solutions
 to the world.

.. OpenShot Video Editor is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.

.. OpenShot Video Editor is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
 along with OpenShot Library.  If not, see <http://www.gnu.org/licenses/>.

.. _upgrade_ref:

Upgrade
=======
Upgrading to a new Marketplace image of OpenShot Cloud API requires migrating data from PostgreSQL and copying files
(``/home/ubuntu/api/video/``). It is only recommended to upgrade if you have a strong need to (for example, a specific
bug fix or new feature). Upgrading can be a technical and tricky process, and is only recommended if needed.
See :ref:`release_notes_ref` for information on recent releases.

Configure the new image
-----------------------
First, it is recommended to configure your new instance/virtual machine (using the same basic settings, IP Addresses, and credentials).
Once configured, update the ``api/api/settings/production-*.py`` file to use the same credentials and settings as before.
NOTE: However we strongly recommend creating a new ``queue``, so the 2 instances do not share a single queue.

Migrate Files
-------------
Next, copy the ``/home/ubuntu/api/video/`` folder from your old instance to your new instance. You can use SSH or SFTP,
or any number of tools or commands. But you must copy this entire folder to your new instance (to the same location).
One method for file transfer that is usually pretty quick: `rsync` (assuming both instances are on the same network).
Commands are listed below as a reference.

.. code-block:: bash
  :caption: Backup and Restore all Video Assets (project files, exports, etc...)

  # Login to OLD instance
  #   Generate SSH key (for your OLD instance to connect to your NEW instance)
  #   (which will create the `~/.ssh/id_rsa.pub` file)
  #   IMPORTANT: Copy public key (the contents of id_rsa.pub file) to the NEW server (`~/.ssh/authorized_keys`)
  ssh-keygen

  # Login to NEW instance
  #   Be sure to add the contents of the above file: id_rsa.pub to the NEW server (`~/.ssh/authorized_keys`)
  #   Alter permissions on video folder (on your NEW instance), otherwise we won't have the permissions
  #   needed to copy files.
  nano ~/.ssh/authorized_keys   // Copy/Paste id_rsa.pub contents here
  cd ~/api/video/
  sudo chown -R ubuntu:www-data *

  # Login to OLD instance
  #   Transfer files to the NEW instance
  cd ~/api/video/
  rsync -arz -i --stats -a --chown=www-data:www-data "output" "ubuntu@NEW-INSTANCE-IP:~/api/video/"
  rsync -arz -i --stats -a --chown=www-data:www-data "files" "ubuntu@NEW-INSTANCE-IP:~/api/video/"

  # Update file permissions on the NEW instance
  #   Since it's possible that some file permissions are now incorrect, let's update them one more time
  cd ~/api/video/
  sudo chown -R ubuntu:www-data *

Migrate Database
----------------
Lastly, backup data from PostgreSQL (Database: openshot_cloud, User: openshot_user), and restore on your new instance.
The database can alternatively be backed up with Django. Examples are provided below that export the DB to a JSON file,
that can be transferred to the NEW instance, and restored.

.. code-block:: bash
  :caption: Backup PostgreSQL Database (**OLD** Instance)

  cd ~/api
  python3 manage.py dumpdata --exclude contenttypes > backup.json
  rsync -arz -i --stats -a "backup.json" "ubuntu@NEW-INSTANCE-IP:~/api/"  # Copy backup.json to NEW instance

.. code-block:: bash
  :caption: Migrate data schema for **older versions** of OpenShot Cloud API

  # Since some database schema changes have happened over the life of OpenShot Cloud API, it might be
  # necessary to migrate the backup.json schema after you have called `dumpdata`. This is recommended, as
  # it also resolves some JSONField formatting issues caused by 'dumpdata'.
  cd ~/api/utilities
  python3 migrate_backup_json.py  // Follow the prompts. This will create a new file with a `-fixed.json` suffix.
  cd ~/api

.. code-block:: bash
  :caption: Restore PostgreSQL Database (**NEW** Instance)

  cd ~/api
  python3 manage.py loaddata -e authtoken.Token backup-fixed.json

Patch & Support
---------------
As an alternative, you can contact cloud-support@openshot.org, and we can happily patch your existing server with our
latest changes. This usually involves adding a public key to your instance, so we can SSH in, and copying our latest
files, and applying any DB changes since your previous version. Because this process can be time consuming, we
can provide you with a quote if you are interested in us patching your server, instead of upgrading things yourself.