Upgrading to pump.io 5.x from 4.x¶
These are the instructions for upgrading pump.io 4.x to 5.x. They will work for any release in the 4.x series and can be used to upgrade to any release in the 5.x series, including beta releases.
Note
If you’re on pump.io 3.x or below, it’s recommended to upgrade to pump.io 4.x before attempting to upgrade to 5.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¶
First, check what Node.js version you’re using. Unless you’ve set up a
Node version manager, node --version should tell you this
information. If you’re using Node 4 or above, you’ll be able to
continue running pump.io without issues. If you’re using Node 0.10 or
0.12, see “Upgrading Node.js” below.
Next, check if your pump.io.json contains an appendFooter
option. If it does, see “Adjusting appendFooter” below.
Finally, the systemd unit file has enabled many security options. If
you have datadir set and its value points to somewhere in
/home or /root, these security restrictions will impact
you. See “Dealing with systemd changes” below.
It is expected that these changes won’t impact any other configurations, but this change is complicated and administrators should allow for extra time to deal with unexpected issues.
After doing this, you should be ready to upgrade your installation.
To run the upgrade, invoke:
$ sudo npm install -g pump.io@5
Note
If you’re trying to upgrade to the latest beta, specify
pump.io@beta instead.
Complete your upgrade by restarting your pump.io process.
For source-based installs¶
First, check what Node.js version you’re using. Unless you’ve set up a
Node version manager, node --version should tell you this
information.
If you’re using Node 4 or above, you’ll be able to continue running pump.io without issues. If you’re using Node 0.10 or 0.12, see “Upgrading Node.js” below.
Next, check if your pump.io.json contains an appendFooter
option. If it does, see “Adjusting appendFooter” below.
Then, check if you’re impacted by changes to the systemd unit file,
which has enabled many security options. If you have datadir set
and its value points to somewhere in /home, or if your
installation’s source code is stored in /home, these security
restrictions will impact you. See “Dealing with systemd changes”
below.
It is expected that these changes won’t impact any other configurations, but this change is complicated and administrators should allow for extra time to deal with unexpected issues.
After doing this, you should be ready to upgrade your installation.
To start the upgrade, fetch new changes, prefixing sudo as
necessary:
$ cd /path/to/your/installation/directory
$ 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 untracked changes
reported by git status, save them with git stash; if you have
committed changes reported by git log, make a note of the commit
ids.
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 5.x series is using git tag - in this case, we’re assuming
that 5.0.0 is the latest available.
$ git checkout v5.0.0
$ npm install
At this point, if you previously ran git stash, you should run
git stash apply. If you made a note of commits, you should tell
Git to apply those commits on the new checkout using git
cherry-pick.
If you just restored template changes, you’ll need to check that they
still work. The icon set has been switched from Bootstrap’s Glyphicons
to Font Awesome, so you should adjust any
icons used in your modifications to match. Underscore (the _
variable) has been replaced with Lodash, a faster implementation that
is mostly (but not entirely) compatible; if
your templates use _ in inline JavaScript, you’ll need to check
that they still work with Lodash.
Additionally, 5.x upgrades Backbone to the 1.3.3 release. If you modified web UI JavaScript, please ensure that it still works with the newer version of Backbone.
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:
$ npm run build
Complete your upgrade by restarting your pump.io process.
Upgrading Node.js¶
As previously announced, pump.io 5.0 drops support for Node 0.10 and 0.12. These versions already operated with degraded cross-site scripting security protections and were preventing important maintenance work.
Most mainstream distributions ship supported versions of Node.js, so if possible, you should upgrade your distribution. If this is not an option, you can use NodeSource to get a newer version of Node.
If you aren’t sure how to move forward, contact the community and they’ll help you sort through your options.
Dealing with systemd changes¶
As of pump.io 5.x, the systemd unit shipped with the package uses the
InaccessiblePaths= option to prevent the daemon from accessing
several common directories in /. It also restricts access to
miscellaneous other system resources and, perhaps most importantly,
sets ProtectHome=true. For more information, refer to
systemd.exec(5).
This is done to reduce attack surface and limit potential damage in
the event that the pump.io process is compromised by a remote
attacker. However, it does introduce problems for anyone who stores
data (whether datadir or the source code itself) anywhere that
ProtectHome=true restricts access to, including /home,
/root, and /run/user. You will need to move all this data to
an accessible location.
Warning
It is perfectly possible to use systemd’s unit fragment
mechanism to override the pump.io service and set ProtectHome
to false. Administrators are strongly encouraged to avoid this
option as there are better solutions and turning it off reduces
installation security.
If you store datadir in /home, the recommended course of
action is to move it to /var/local/pump.io. Other reasonable
choices include /var/lib/pump.io, /srv/pump.io or
/srv/http/pump.io. These suggestions are based on hier(7) and
the Filesystem Hierarchy Standard, but really the place
you pick is not terribly important as long as systemd allows access to
it. Note that all of both /var and /srv are left accessible
specifically for this purpose. When moving datadir, don’t forget
to adjust your pump.io.json to match.
If you have an npm-based install, this is all you need to worry about. However, if you have a source-based install and you store pump.io’s source code in a location restricted by systemd, pump.io will be unable to start.
There are two solutions to this:
Move the source code somewhere else.
/srvor/usr/local/libmight be good choices for this.Switch to managing pump.io as a global npm install, but installing from your local source code instead of from npm. To do this, make sure you’re in the directory with your source code, then run
sudo npm install -g --production .. You can then manage pump.io as if it was installed from npm, except that the source code will correspond to your local checkout. See npm-install(1) for how this works.This will be the recommended from-source install method in the future.
If you have any questions, aren’t sure how to pick, or don’t understand what’s going on, get in touch with the community.