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.

Adjusting appendFooter

pump.io adds a period and a space after the text in the footer, before appendFooter‘s value is interpolated.

To account for this, simply remove these characters from the beginning of appendFooter in your pump.io.json, or adjust appendFooter some other way if you didn’t previously have these characters.

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:

  1. Move the source code somewhere else. /srv or /usr/local/lib might be good choices for this.

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