Generic source-based install


The project strongly recommends against source-based installations. They’re harder to upgrade and the chances of the administrator making a mistake during installation is far higher.

Unless you have a very good reason for doing this (for example, you need to patch the source code), you should do an npm-based install instead.

Feel free to ask the community if you’re not sure about your particular situation.

First, install the prereqisites. Package names will vary across distributions. In particular, how to install npm may vary significantly, as some distributions ship severely outdated versions of npm (or don’t ship npm packages at all). Feel free to ask the community for help.

Once you have the prerequisites set up, you should clone the git repository:

git clone

You can then install the dependencies using npm:

npm install
npm run build

If you want to test the install, you can run:

npm test

These tests are run on every commit to the codebase so they won’t catch actual bugs, but they may catch simple installation problems. You can run them if you want, but they take a while so this step is super optional.

You can now proceed to configuring The recommended way for an source-based install is to use JSON configuration files. You will also almost certainly want to set up HTTPS at this point, perhaps using Certbot and Let’s Encrypt.


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.