Upgrade from substance 0 to 1

Upgrading from substance 0 to 1 requires moving your dependencies from Python 2 to Python 3 and VirtualBox 6.0.

Upgrading on macOS

1. Stop all your engines:

   $ substance engine ls
   $ substance engine halt <ENGINENAME> # Do this for every running engine
   

2. Uninstall substance:

   $ sudo pip uninstall substance
   

3. Upgrade VirtualBox to 6.x:

   - Visit https://www.virtualbox.org/wiki/Downloads
   - Install the package on your computer.
   - Your existing machines and engines should remain intact.
   

4. Upgrade Python to Python 3:

   $ brew uninstall python
   $ brew uninstall python@2
   $ brew install python
   

5. Install substance:

   $ sudo pip3 install substance
   

6. Upgrade your engine by either creating a new engine.

Upgrading on Windows

1. Stop all your engines:

   $ substance engine ls
   $ substance engine halt <ENGINENAME> # Do this for every running engine
   

2. Uninstall substance via cygwin:

   $ sudo pip uninstall substance
   

3. Upgrade VirtualBox to 6.x:

   - Visit https://www.virtualbox.org/wiki/Downloads
   - Install the package on your computer.
   - Your existing machines and engines should remain intact.
   

4. Upgrade Python to Python 3:

• Run the Cygwin setup (setup-x86_64.exe)
• Remove python, python-devel and python-pip
• Add python3, python3-devel, python3-pip

1. Install substance using the Cygwin terminal:

   $ sudo pip3 install substance
   

Upgrading on Linux

1. Update your system.:

   # Debian/Ubuntu
   $ sudo apt-get update && sudo apt-get upgrade
   
   # Arch
   $ sudo pacman -Syu
   

2. Reboot:

   - needed in case the virtualbox kernel modules were updated.
   

3. Stop all your engines:

   $ substance engine ls
   $ substance engine halt <ENGINENAME> # Do this for every running engine
   

4. Install python3:

   # Debian/Ubuntu
   $ sudo apt-get install -y python3.7 python3-pip
   
   # Arch
   $ sudo pacman -S python python-pip
   

5. Update substance:

   $ sudo pip3 install substance
   

6. You will need to create a new engine so that it can use the newest docker image and virtualbox version:

   $ substance engine create <ENGINENAME>
   

Post-Install steps

1. After upgrading to substance 1.x, you should take a moment to update your jinja templates to use Python 3 syntax.

   # example:
   # dockwrkr.yml.jinja
   
     [...]
   
     VAR_NMAILER_REMOTE_PORT: "587"
     VAR_NMAILER_REMOTE_USER: ""
     VAR_NMAILER_REMOTE_PASS: ""
     {%- for k, v in SUBENV_VARS.iteritems() %}
   
   # becomes
   
     [...]
   
     VAR_NMAILER_REMOTE_PORT: "587"
     VAR_NMAILER_REMOTE_USER: ""
     VAR_NMAILER_REMOTE_PASS: ""
     {%- for k, v in SUBENV_VARS.items() %}
   

Known issues

1. If you get a CryptographyDeprecationWarning when running substance commands, it’s because of this issue. As noted, a workaround is running sudo pip install cryptography==2.4.2 until the problem is fixed in paramiko.