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