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.