Setup on Debian “jessie” stable

We’re going to install from the npm registry, use MongoDB for the database and proxy behind the nginx web server.

Install basic requirements

Install the requirements via the Debian package manager.

$ sudo apt-get install mongodb nginx graphicsmagick git

Debian jessie provides nodejs of version 0.10, while after version 2.0.0 beta 1 requires nodejs 4.x. Therefore, it must be updated from upstream.

$ curl -sL | sudo bash -
$ sudo apt-get install -y nodejs

You may want to also consider running sudo rm -r /usr/local/lib/node_modules to remove all currently-installed npm packages. Blowing away everything already installed is optional but strongly recommended as npm v1 (which is shipped by Debian) is prone to creating broken, half-installed directory structures that interfere with future installations. In addition, Debian’s npm has a default install path of /usr/local/lib/node_modules, whereas upstream installs to /usr/lib/node_modules. Simply removing the former path makes everything much less confusing.

If you want to keep your currently-installed packages the best way to do so is to save the list of installed packages, proceed with the removal, then reinstall using upstream npm. Conveniently, you can get a list of installed packages by doing npm ls -g --depth=0 --prefix=/usr/local.

Install and set up

Next, we create a pumpio user and group and create the needed folders:

$ sudo groupadd pumpio
$ sudo useradd -d /var/lib/pumpio -m -r -g pumpio pumpio

$ sudo mkdir -p /var/lib/pumpio/uploads
$ sudo chown -R pumpio:pumpio /var/lib/pumpio/uploads

$ sudo mkdir /var/log/pumpio/
$ sudo chown pumpio:pumpio /var/log/pumpio/

Next, install itself, along with the MongoDB Databank driver:

$ sudo npm install -g databank-mongodb@0.19.2

Finally needs a configuration file in /etc/ with the following content (adapted to your situation):

    "driver":  "mongodb",
    "params": {"host":"localhost","dbname":"pumpio"},
    "hostname":  "",
    "address": "",
    "port": 8080,
    "urlPort": 443,
    "secret":  "somerandomstringhere",
    "key":  "/path/to/your/ssl-cert.crt",
    "cert":  "/path/to/your/ssl-cert.key",
    "noweb":  false,
    "site":  "",
    "owner":  "Your Name",
    "ownerURL":  "",
    "nologger": false,
    "logfile": "/var/log/pumpio/pumpio.log",
    "serverUser":  "pumpio",
    "datadir": "/var/lib/pumpio",
    "enableUploads": true,
    "debugClient": false,
    "firehose": "",
    "disableRegistration": true,
    "noCDN": true,
    "requireEmail": false,
    "compress": true,
    "smtpserver": "localhost",
    "proxyWhitelist": ["", "", ""]

In particular you need to replace which your actual domain name.


If you’re connecting your site with other software (such as federated servers or using Web clients), please note that most of them save OAuth keys based on your hostname and listening port. The following changes may make your relationships stop working.

  • Change of hostname
  • Change of port (from 8000 to 80 or even from HTTP to HTTPS)
  • Clearing your database or clearing some tables
  • Changing user nicknames

We realize that these kind of changes are normal when someone’s experimenting with new software, and there are (early, tentative) plans to make the software more robust in the face of this kind of change without sacrificing security, but for now it’s a good idea to decide on your “real” domain name first before making connections to other sites.

Make sure that the pumpio user can access your SSL certs.

You can now try and see if it works:

$ sudo -u pumpio pump

This starts up running on port 8080, this will be proxied behind nginx which will serve it on port 443 (https).

Setup nginx proxying

Create the file /etc/nginx/sites-available/pump with the following content (adapted to your situation):

upstream pumpiobackend {
  server max_fails=3;

server {
  rewrite ^$request_uri?;

server {
  listen 443 ssl;

  ssl_certificate  /path/to/your/ssl-cert.crt;
  ssl_certificate_key  /path/to/your/ssl-cert.key;

  access_log /var/log/nginx/pumpio.access.log;
  error_log /var/log/nginx/pumpio.error.log;

  client_max_body_size 500m;

  keepalive_timeout 75 75;
  gzip_vary off;

  location / {
    proxy_http_version 1.1;
    proxy_set_header Host $http_host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Real-IP $remote_addr;

    proxy_redirect off;

    proxy_buffers 16 32k;
    proxy_cache off;
    proxy_connect_timeout 60s;
    proxy_read_timeout 60s;
    proxy_pass https://pumpiobackend;

    proxy_pass_header Server;

You will of course have to provide your own SSL cert and put them in the right path. Make sure that the certificate key is not world readable! Currently the easiest (and cheapest) way to get such a certificate is by using Certbot and Let’s Encrypt.

Finally you can link the file you created to enable it (in a root shell):

# cd /etc/nginx/sites-enabled
# ln -s ../sites-available/pump .

If everything is set up correctly you should now be able to restart nginx and access the site in your web browser:

$ sudo systemctl restart nginx

Before you start using your site make sure have settled on the correct hostname. You can’t switch that around later without breaking federation badly.

Start automatically using systemd

You probably want to make sure is started at boot and monitored thereafter. You can accomplish this with systemd, and ships a systemd file specifically for this purpose.

To use said systemd file, see using the upstream systemd unit.

If everything seems to be working, you’re done! Congratulations!


If you later wish to upgrade your server software, e.g. to the latest version on npm (or even to git master), you can do something like the following. (Note: you might want to backup your database first using mongodump, see the migration notes below.)

First, stop and switch to the pumpio user.

$ sudo systemctl stop

Next, install the latest version with npm:

$ sudo npm install -g

It’s a good idea to update the database stuff at the same time:

$ sudo npm install -g databank-mongodb@0.19.2

If you’re unsure, especially after a big upgrade, you can always test it first directly by running sudo -u pumpio pump as above. If all seems well you can Ctrl-C and start it for real.

$ sudo systemctl start