.. _rce-upgrade-2x:

Upgrade From |RCEE| 1.x or 2.x
------------------------------

.. important::

    As of |RCEE| 3.x all instances are managed through |RCC|. You need to first
    :ref:`rcc-linux-ref` or :ref:`rcc-windows-ref` and then proceed with
    the information contained within this section.

.. _mysql-upgrade:

Pre-requisite for MySQL
^^^^^^^^^^^^^^^^^^^^^^^

MySQL has two pre-requisites that should be addressed before upgrading to
ensure that it goes smoothly.

* Do not use `localhost` in the database connection string.
* InnoDB must be the database engine

Setting MySQL Connection
~~~~~~~~~~~~~~~~~~~~~~~~

To ensure that |RCC| can properly import and upgrade your instance of |RCEE|
you need to make the following configuration change before you start.

1. Open your :file:`production.ini` file, the default location is
   :file:`~/rhodecode/data` for pre-2.2.7 versions.
2. If you have ``localhost`` set, change the database connection string to
   specify the IP Address . See the following example for details.
3. Once saved you can proceed with the import and upgrade steps.

.. code-block:: ini

    #########################################################
    ### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG    ###
    #########################################################

    # MySQL DB Connection
    sqlalchemy.db1.url = mysql://root:qweqwe@localhost/rhodecode ## If localhost
    sqlalchemy.db1.url = mysql://root:qweqwe@127.0.0.1/rhodecode ## Change to IP


Setting MySQL InnoDB Engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Older versions of |RCEE| such as versions 1.5 or 1.7 may be running with a
MySQL database which uses MyISAM as the tables engine. |RCEE| requires MySQL
databases to use InnoDB as the tables engine.

To upgrade your MySQL database to use InnoDB as the tables engine, see the
following example:

.. code-block:: sql

    # To alter a table engine
    ALTER TABLE <table_name> ENGINE=InnoDB;

    # A one-liner for all tables
    for t in `echo "show tables" | mysql --batch --skip-column-names rhodecode_database`;
        do mysql rhodecode_database -e "ALTER TABLE\`$t\` ENGINE = InnoDB;";
        done

Pre-requisite for Licence Management
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. important::

    It is better to contact us before you upgrade so that you have
    a matching licence token/key pair. Otherwise upgrading from a 1x or
    2x version to a |RCEE| 3.x version could result in down time. For license
    inquiries, see the
    :ref:`Licence Management <enterprise:admin-tricks-license>` section.

If you upgrade without a new licence key, your |RCEE| instance will display a
licence token on the following page:
:menuselection:`Admin -- Settings --> License`. Once upgraded, contact us
with this licence token and we can send you the matching licence key.

If you have received a licence/token key pair, use the following instructions to
configure them.

1. Update the Licence Token in :file:`/home/user/.rccontrol/{instance-id}/rhodecode.ini`

.. code-block:: ini

    ## generated license token, goto license page in RhodeCode settings to obtain
    ## new token
    license_token = <add token here>

2. Once the token has been changed, the licence key provided can be entered on
   the RhodeCode Enterprise Interface under
   :menuselection:`Admin --> Setting --> Licence`.

.. important::

   If you upgrade without a valid licence key, all users except *Admin* will be
   locked out of the new instance. If you cannot wait to contact us, you can
   run a new installation in parallel using a trial licence while
   maintaining your previous version, see :ref:`multi-instance`.

If you wish to upgrade your version of |RCEE| from the command line,
use the following steps.

1. :ref:`stop-rce-old`
2. :ref:`import-rce`
3. :ref:`install-vcsserver`
4. :ref:`upgrade-to-rcee`

.. _stop-rce-old:

Stop your |RCEE| Instance
^^^^^^^^^^^^^^^^^^^^^^^^^

If you wish to use the same port for serving |RCEE|, you should stop the running
instance before continuing. Pre-2.2.5 versions took the following
command syntax:

.. code-block:: bash

    $ sudo /etc/init.d/rhodecode {start | stop | restart | status}

.. _import-rce:

Import |RCEE| into |RCC|
^^^^^^^^^^^^^^^^^^^^^^^^

Importing is a necessary step as |RCC| now manages all of the dependencies
needed for |RCEE|.

To import |RCEE| into |RCC|, use the following steps.

1. Identify the :file:`production.ini` file that manages your current |RCEE|
   installation. The default location is :file:`~/rhodecode/data/`.

2. Use the ``rccontrol import`` command with the ``Enterprise`` argument,
   and specify the path to :file:`production.ini`.

   |RCC| uses this file to create a new
   :file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file. This
   imports your |RCEE| settings and points your new instance to the original
   repository directory.

   The :file:`production.ini` file also points to the |RCEE| database,
   which contains your permissions and user management settings. |RCC|
   imports this database and upgrades it as needed.

3. During import, set a new port if prompted.

.. code-block:: bash

    # Import your current version
    $ rccontrol import Enterprise /home/{user}/rhodecode/data/production.ini
    Parsing "/home/{user}/rhodecode/data/production.ini":
    - host: 0.0.0.0
    - port: 5000
    - database: sqlite:////home/{user}/rhodecode/data/rhodecode.db?timeout=60
    Port is not accessible
    # Set a new port
    # You will be asked for this if you don't stop your running instance
    Port for the Enterprise server to use [5000]: 5500

    Importing to instance: enterprise-2
    Version detected: 2.2.3

    Installing RhodeCode Enterprise

.. _install-vcsserver:

Install a |VCS|
^^^^^^^^^^^^^^^

You need to configure a |VCS| to run |RCEE| 3.x with full functionality. If you
install a |VCS| prior to installing |RCEE|, it will automatically be connected
to your instance during installation. If you need to manually configure the
connection afterwards, see the :ref:`manually-vcsserver-ini` section.

To install a |VCS| to work with your new instance of |RCEE|,
use the following example:

.. code-block:: bash

    # Install a VCS Server for your instance
    $ rccontrol install VCSServer

    Agree to the licence agreement? [y/N]: y
    IP to start the server on [127.0.0.1]:
    Port for the server to start [10000]:
    Creating new instance: vcsserver-1
    Installing RhodeCode VCSServer
    ...
    Extracting VCSServer ...
    Configuring RhodeCode VCS Server ...
    Supervisord state is: RUNNING
    Added process group vcsserver-1

    # Check the VCS Server details
    $ rccontrol status

     - NAME: vcsserver-1
     - STATUS: RUNNING
     - TYPE: VCSServer
     - VERSION: 3.5.0
     - URL: http://127.0.0.1:10000

.. _upgrade-to-rcee:

Upgrade to the latest |RCEE|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Once imported, you can now upgrade your instance to |RCEE| using the
``rccontrol upgrade`` command.

If you require a specific version, specify it with the ``--version``
argument. You can also check the status of all running instances with the
``rccontrol status`` command.

Use the following example to upgrade to the latest version.

.. code-block:: bash

    # Import original instance as explained above
    $ rccontrol import Enterprise production.ini

    # Install a VCS Server as explained above
    $ rccontrol install VCSServer

    # Check the status of them
    $ rccontrol status

     - NAME: enterprise-1
     - STATUS: RUNNING
     - TYPE: Enterprise
     - VERSION: 1.5.0
     - URL: http://127.0.0.1:10000

     - NAME: vcsserver-2
     - STATUS: RUNNING
     - TYPE: VCSServer
     - VERSION: 3.5.0
     - URL: http://127.0.0.1:10001

    # Upgrade from version 1.5.0 to 3.5.0
    $ rccontrol upgrade enterprise-1 --version 3.5.0

    Checking for available update for enterprise-1 @ 1.5.0
    Stopped enterprise-1
    Initiating upgrade to version 3.5.0
    ...
    ****************************************
    *** UPGRADE TO VERSION 45 SUCCESSFUL ***
    ****************************************

    Note that RCE 3.x requires a new license please visit https://rhodecode.com/u/license-upgrade

    Upgrade of RhodeCode Enterprise successful.
    Auto starting enterprise-1