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 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.
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.
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.