Upgrading to pump.io 3.x from 2.x
==================================

These are the instructions for upgrading pump.io 2.x to 3.x. They will
work for any release in the 2.x series and can be used to upgrade to
any release in the 3.x series, including beta releases.

.. NOTE:: If you're on pump.io 1.x or below, it's recommended to
          upgrade to pump.io 2.x before attempting to upgrade to
          3.x. It's not strictly necessary, but it makes things easier
          if things go wrong since there's less changes that could be
          causing problems.

If at any point you run into trouble, contact the `community
<https://github.com/e14n/pump.io/wiki/Community>`_ and they'll be
happy to sort you out.

For npm-based installs
----------------------

pump.io 3.x obsoletes the ``uploaddir`` configuration option and
replaces it with ``datadir`` and ``enableUploads``. For details, see
`issue #1261 <https://github.com/pump-io/pump.io/issues/1261>`_.

If your ``pump.io.json`` does not include an ``uploaddir``
configuration value, you're unaffected by this change. Skip to the
``npm install`` command below.

If it does, you'll need to migrate to the ``datadir`` configuration
option. See "Migrating to ``datadir``" below.

To run the upgrade, invoke:

::

   $ sudo npm install -g pump.io@3

.. NOTE:: If you're trying to upgrade to the latest beta, specify
          ``pump.io@beta`` instead.

Complete your upgrade by starting or restarting your pump.io process.

For source-based installs
-------------------------

pump.io 3.x obsoletes the ``uploaddir`` configuration option and
replaces it with ``datadir`` and ``enableUploads``. For details, see
`issue #1261 <https://github.com/pump-io/pump.io/issues/1261>`_.

If your ``pump.io.json`` does not include an ``uploaddir``
configuration value, you're unaffected by this change. Skip to the
``npm install`` command below.

If it does, you'll need to migrate to the ``datadir`` configuration
option. See "Migrating to ``datadir``" below.

There are several steps needed to run an upgrade. First, fetch new
changes:

::

   $ cd /path/to/your/installation/directory
   $ sudo git fetch

If you've modified templates, you need to save the changes you've
made. You can check to see whether you've made changes by running
``git status`` and ``git log`` - if you have, save them to a file.

.. NOTE:: If you're a proficient git user, you may find it easier to
          ignore these instructions and instead commit your changes,
          checkout the new tag, then cherry-pick the commit you just
          made.

Now, discard the changes you've just saved:

::

   $ sudo git checkout .

At this point, ``git status`` should report a working directory with
no modified files.

Now that we're prepared, we'll perform the upgrade itself by checking
out the relevant tag. You'll have to check what the latest version in
the 2.x series is using ``git tag`` - in this case, we're assuming
that 2.0.5 is the latest available.

::

   $ sudo git checkout v2.0.5
   $ sudo npm install

At this point, if you had previously saved template modifications, you
should now use the information you saved to separate files to restore
your modifications. The templates haven't changed significantly, so a
line-by-line diff will probably apply directly with little to no
conflicts.

If you just restored template changes, it's recommended that you run
the linting process to ensure that your changes are high-quality and
consistent with surrounding code:

::

   $ npm run lint:jade

Finally, regardless of whether or not you modified templates, you need
to rebuild client-side template resources which aren't checked into
git:

::

   $ sudo npm run build

Complete your upgrade by starting or restarting your pump.io process.

Migrating to ``datadir``
------------------------

Otherwise, you need to migrate your storage directory. First, shut
down your pump.io server. How to do this will vary depending on what
supervisor you use to manage it. For example, if you're using systemd
with a unit named ``pump.io.service``, you might do:

::

   $ sudo systemctl stop pump.io

Next, determine if your ``uploaddir`` ends in ``/uploads``. If so, all
you have to do is edit ``uploaddir`` to be named ``datadir``, remove
``/uploads`` from the end of the path, and add a new line that sets
``enableUploads`` to ``true``. After these steps, you're done
migrating and can skip to the ``npm install`` command below.

If your ``uploaddir`` does `not` end in ``/uploads``, your migration
process is a little more complicated. First, move your old uploads
directory somewhere else. For example, if it was stored at
``/var/lib/pumpio``, you might do:

::

   $ sudo mv /var/lib/pumpio /var/lib/pumpio.bak

Next, create a new directory where your uploads directory used to be,
setting the owner and group to your ``serverUser`` (assumed to be
``pumpio`` in this example):

::

   $ sudo mkdir /var/lib/pumpio
   $ sudo chown pumpio:pumpio /var/lib/pumpio

Next, move your old uploads directory back into the new directory,
giving it the name ``uploads``. For example:

::

   $ sudo mv /var/lib/pumpio.bak /var/lib/pumpio/uploads

The last step in the migration is editing your ``pump.io.json``. Find
the ``uploaddir`` option and change it to use ``datadir``. Then, add a
new configuration value called ``enableUploads`` and set it to
``true``.

You're now done migrating to ``datadir`` and should return to where
you were before in this document.