FAQ for pod maintainers

We've started adding questions that we're frequently asked to this page, but it doesn't cover everything. If you have other questions, the best way to get an answer quickly is to visit us in our IRC channel.

Installation Information

What are the general system requirements?

Running diaspora* requires resources depending on how many users use the installation and how much traffic the installation receives from other pods. Generally it is recommended that at least 1 Gig of memory should be available for even small instances.

For pods with more users the amount of memory available to diaspora* and the background jobs it needs is higher depending on the amount of users actively using the instance. As the database grows, more memory will be needed to compensate.

Since diaspora* requires quite a lot of different components to be installed, generally shared hosting servers are not sufficient. Any VPS or dedicated server with a suitable amount of memory will suffice.

Do you have a detailed installation guide?

Yes. Check it out! It will probably be more up-to-date than this page, in general.

What ports does diaspora* need open for communication?

Since we recommend running on HTTPS you should only need to open the standard port for it: 443. You should have a reverse proxy listening there that forwards the requests to the application server that diaspora* starts, on port 3000 by default. You can use your existing Nginx or Apache to do that. While we don't recommend it, you can run on plain HTTP with its standard port 80 too. Just never let diaspora* listen on these ports directly. You don't need to open the application server port, 3000, it's for internal communication only.

Can I use Apache to run diaspora*?

Yes: diaspora* is a standard Rails application, so you can run it with Passenger, or doing the more common setup which is to use a reverse proxy configuration. Check this example on how to configure that setup.

Do I need a commercial SSL certificate? / Can I use CAcert certificates?

If you plan on running your pod over HTTPS (yes, you should!) then yes you will need a valid commercial SSL certificate. By design, federation will not work with pods that have self-signed or invalid SSL certs installed. We do this to ensure that all users in the network are able to use diaspora* without suffering from constant security warnings related to 'invalid' certs.

For more information see this and this discussion.

There are free commercial certificates around - check Let's Encrypt for example (acme.sh makes the process a bit more simple).

How can I run multiple load-balanced instances of diaspora*?

Multiple diaspora* instances for the same "pod" must share SQL and Redis databases, and public/uploads directories. There are many possible ways to accomplish this, but perhaps the most classical scenario would be to configure all the nodes to point at a central database server for MySQL/Postgres and Redis, and share the uploads directory from a file server via NFS. To avoid problems with schema changes, it would be desirable to keep all of the instances running the same version of diaspora* at all times.

Load-balancing of the instances can be accomplished with any TCP load balancer that supports session stickiness (such as Apache or nginx, among others).

How can I restart diaspora* without any downtime?

By default, diaspora* uses Puma to serve requests. In production mode, it's possible to do a graceful restart of the Puma process to avoid downtime. This command, executed in the directory of your diaspora installation, will spawn a new master process, loading any code/configuration changes that you've made:

RAILS_ENV=production bin/pumactl -F config/puma.rb restart

As the new master spawns workers, old workers finish their requests and are removed from the old master until the last new worker is spawned, at which time the old master is shut down.

Note: this only applies for 0.9.0.0 or newer.

Troubleshooting

I installed diaspora* on my machine, went to http://localhost:3000 and signed up. But my friends can't add me!

You set "localhost" as your address, but this is not a valid external address. You first need an externally accessible address - either a domain name or an IP address. Once you have that working, you need to clear your database (`$ bundle exec rake db:drop db:create db:migrate`) and re-register, coming in via the external URL. Note that if your externally accessible address changes, you need to start over. diaspora* is designed as a server application to run all day and night.

I get 'command not found' if I run bundle install

Make sure RVM is loaded and the correct Ruby version and gemset are activated. The output of the rvm info and gem env commands can be helpful in that. Run gem install bundler to reassure bundler is actually installed.

If you don't use RVM, a common issue is that Debian-based distributions, including Ubuntu, don't add gem executables to the search path. Read up on the PATH environment variable on how to solve that.

How do I get past the sign-in page to create a new account?

To create a new account, go to http://yourdiasporainstance.tld/users/sign_up (replacing yourdiasporainstance.tld with the host name of your pod).

I installed diaspora* on my machine, but when I load the site there are no images and the layout looks horrible!

You most likely started diaspora* in production mode and accessed the application server directly and not through your reverse proxy. In production mode we expect your reverse proxy to serve the static content since it does the job way better than anything else. If you did access diaspora* through a reverse proxy, make sure it has no configuration issues, has the public/ directory as document root and is set to look up if requested files are found there before directing the request to the application server.

Also make sure you ran bundle exec rake assets:precompile.

If you need to work around this requirement you can turn environment.assets.serve to true in config/diaspora.toml.

There are no uploaded images on my pod

First make sure other static content is working, as described in the previous section. We embed uploaded images with their full URL, this has to do with the way diaspora* makes sure your images can be seen by users on other pods. A common problem here is that environment.url in config/diaspora.toml, from which diaspora* constructs the full URL, is set to an incorrect value.

I can't find anybody on another pod / I am receiving posts but nobody is receiving mine

If you're having problems, make sure to search for people by their full diaspora* ID. Check that your Sidekiq worker is running. Check Sidekiq's retry queue for error messages. Check that the environement.certificate_authorities setting is correct.

I can't find myself from another pod / I am not receiving any posts but everybody is receiving mine

Check that your SSL setup is correct, use sslshopper, ssllabs or High-Tech Bridge to test your configuration. Make sure it's all green, no yellow, no red.

How can I troubleshoot my email configuration?

Use the following command to send an email and get the exceptions right on your console:

RAILS_ENV=production bundle exec rails runner 'Notifier.admin("test message", User.where(username: "your_username")).each(&:deliver_now)'

Make sure to restart diaspora* once you successfully receive the test message.

I'm getting a 500 error page

Oh noes, you might have hit a bug in diaspora*! But this can also be caused by setup issues, like a incorrectly setup custom landing page, an old Redis version or database connectivity issue.

1. Make sure you found a reliable way to reproduce the issue.
2. Run tail -f log/production.log. Watch the output closely as you reproduce the issue.
3. If you can't make sense out of the actual error message, reach out to us, see How we communicate. When doing so provide the steps you have taken to produce the error page as well as the full output from the log while reproducing it.
4. If told to open an issue, go to https://github.com/diaspora/diaspora/issues. Again make sure to provide the steps to reproduce the problem as well as the log output.

I'm getting an error when starting ./script/server

If you get undefined symbol: sigar_skip_token, you need to run in your diaspora* server directory:

GEM_HOME=vendor/bundle/ruby/2.4.0 gem uninstall sigar
bin/bundle config --local build.sigar "--with-cppflags='-fgnu89-inline'"

Afterwards, you need to re-run the bundle install command from the installation instructions.

Upgrading

Is there anything I should do before upgrading my installation?

Yes, read our notes for updating.

How do I roll back my installation if an update breaks it?

First, try to fix your installation; as always our IRC channel should be helpful for getting help with this.

To roll back, just do: git checkout ref Where ref is the identifier of the commit to go back to. It's a long string of letters and numbers. You can find the ref by doing a git log, eyeballing the commit dates, and figuring out where you were before you pulled. Of course it's best if you keep track of that ref before you update.

You can also checkout a particular version with git checkout v0.3.0.1, replacing the version of course.

After that just follow the same procedure that you would to update your installation.

What if there were database migrations in the code I am rolling back?

Then you also need to roll those back separately. You need to do this before you roll back the code. Look in the db/migrate directory and figure out which files are new since the last time you pulled - i.e., which migration your database should be on. They are in timestamp order in that directory. Then do: bundle exec rake db:rollback and look at the output. It will tell you which migration you are now on. It rolls back one each time you run it. Run it until you're on the right migration and then roll back the code as described above.

Also be aware that database rollbacks can fail - they depend on the migration author writing the correct code to roll back. So in this case it's generally much easier to seek help to fix your current setup than to roll it back.

General

How can I receive project news? (Updates, Security fixes, ...)

There are multiple channels for important news, including:

• the official diaspora* project account: hq[at]pod.diaspora.software.
• the official blog at blog.diasporafoundation.org, which also offers an Atom feed.
• the announcements category on Discourse, to which you can subscribe if you have a Discourse account.

Am I alone here? (Establish connections with other pods)

Once you set up your pod, you should add some contacts to start receiving content from other pods. It's a good idea to add some active diaspora* people to your contacts, because they almost all run their own pod, so your pod will be known by them and you will be easily findable from there.

Here is a small list:

• Official account of the project: hq[at]pod.diaspora.software
• Sean Tilley: deadsuperhero[at]joindiaspora.com
• Jonne Haß: jhass[at]diaspora.social
• Jason Robinson: jaywink[at]jasonrobinson.me
• The Geraspora team: team[at]pod.geraspora.de
• Waithamai: waithamai[at]pod.geraspora.de
• Fla: fla[at]diaspora-fr.org

After you added a few contacts it's a good idea to make a public post containing the #newhere tag, announcing your new pod, to get even more contacts.

Can I make my pod private/isolated/not communicate with other pods?

No. diaspora* is built around the idea of a distributed social network. We want to build one network, not enable special interest communities or companies to host their own social network (We do welcome you on diaspora* though!). A large amount of the development effort goes into making that one network possible and the whole user experience is designed around it. This not only means that other existing solutions often have feature-sets way better suited to that usecase, but also that if we did implement a switch to turn off communication with other pods, there would be many broken ends in the user interface, which would lead to a bad user experience.

Can I modify the code?

Yes. But keep in mind that diaspora* is licensed under the AGPLv3, that means you must make the currently running source code available to your users. For legal advice beyond that, please contact your lawyer.

Will a pod eventually receive federated posts that it misses while being offline/down?

Possibly. We retry the delivery three times at one hour intervals.

I've got my pod running. How do I disable outside logins?

Set settings.enable_registrations to false in your config/diaspora.toml and then restart diaspora*.

How do I back up my pod?

You should do backups of all user data, that is the whole database and uploaded images. For the images just make copies of the public/uploads directory. Then just dump all Diaspora_ databases from your database server. A web search should get you the information you need on how to do that. Make sure to store the backups on a different server, or at least on a different hard drive.

For more details, see Pod data backup.

I am on PPC (e.g. old iMac) and want to use it for serving diaspora*, but there is no ExecJS compatible JS runtime

One thing you could do, assuming you have another PC that will run Node: Precompile your assets on that machine (using bundle exec rake assets:precompile) and then check them into git before you deploy to the PPC box, or just copy over the contents of public/assets. The Javascript runtime is only really needed for precompiling assets and shouldn't be loaded at all in the actual production environment. You may need to use git add public/assets -f to force git to check them in, since I think that directory is in .gitignore.

What are roles and how do I use them? / Make yourself an admin or assign moderators

Note:

Since diaspora* 0.7.8.0, you can add admin and moderator roles in the admin panel inside diaspora*. Search for a user and change the role there. You still need to make the first admin manually as described below to have access to that page

We have a role system that allows to make some accounts 'special' during runtime, without restarting the server.

Currently you can manage the community spotlight, the moderators and the admins through this system. If you are using PostgreSQL, ensure you have set the environment variable DB='postgres' or you will get a very misleading error from bundler and if you follow it, accidentally install the MySQL adapter.

Start by starting a Rails console, using this command in directory of your diaspora gem (usually /home/diaspora/diaspora):

RAILS_ENV=production bundle exec rails console

You'll get a new shell where you can enter Ruby code. To exit it just press Ctrl+D or type exit or quit. Here are some examples to manage the roles, replace the_username with the user's username, not their full diaspora* ID:

Role.add_admin User.where(username: "the_username").first.person           # Add an user as admin by username
Role.add_admin User.where(email: "the_email").first.person                 # Add an user as admin by email
Role.add_moderator User.where(username: "the_username").first.person       # Add an user as moderator by username
Role.add_moderator User.where(email: "the_email").first.person             # Add an user as moderator by email
Role.add_spotlight User.where(username: "the_username").first.person       # Add an user to the 'community spotlight' by username
Role.add_spotlight User.where(email: "the_email").first.person             # Add an user to the 'community spotlight' by email
Role.add_spotlight Person.where(diaspora_handle: "username@pod.tld").first # Add an user to the 'community spotlight' by diaspora handle (other pod), make sure that at least one user of your pod follows that account

For admins: your user profile should now have an "Admin" link added to the mouse hover list. This gives you stuff like user search and stats for your pod.
For moderators: The moderator should now have an "Moderator" link added to the mouse hover list. Moderators have access to the report section of the admin panel and can review reported posts and comments. Moderators also get emails when a new comment or post is reported.

Followed tags don't work on my pod

There is no synchronization in diaspora*. This means your pod only knows about posts it has received for a purpose. These purposes are, of course: the author is local, someone on your pod is following the post's author, or the post's author is following someone on your pod. Another reason is that the post got reshared by someone whom one of the users on your pod follows. Tags are not federated to all pods: the #Followed Tags stream displays only posts your pod knows about through one of the previous scenarios.

My log files are getting huge, help!

Configure yourself a log rotation solution. For example, on Linux distros, do this with logrotate, something like the following (change the paths where needed) in /etc/logrotate.d/diaspora:

/home/diaspora/diaspora/log/*.log {
   notifempty
   copytruncate
   missingok
   compress
   monthly
   delaycompress
   rotate 5
}

Once you've added the file to "/etc/logrotate.d/" run

sudo logrotate -f /etc/logrotate.conf

How can I send an email to a user / a group of users?

You need a working email configuration. There are two ways for triggering the emails.

Ruby console

Fire up your rails console with RAILS_ENV=production bundle exec rails console, then follow one of the examples or make up your own:

Notifier.admin("important message", User.where(username: "someuser")).each(&:deliver)                  # Send a message to someuser
Notifier.admin("important message", User.where(username: ["someuser", "anotheruser"])).each(&:deliver) # Send a message to a group of users
Notifier.admin("important message", User.yearly_actives).each(&:deliver)                               # Send a message to all active users

Rake task

There is a Rake task podmin:admin_mail available to allow podmins to easily send news and notices to users. The rake task triggers emails via the normal diaspora mailer mechanism (so they are embedded in the standard template) and takes the following parameters:

 1) Users definition
   all - all users in the database (except deleted)
   active_yearly - users logged in within the last year
   active_monthly - users logged in within the last month
   active_halfyear - users logged in within the last 6 months
 2) Path to message file
   Give here a path to a HTML or plain text file that contains the message.
 3) Subject
   A subject for the email

Example shell command (depending on your environment);

RAILS_ENV=production bundle exec rake podmin:admin_mail['active_monthly','./message.html','Important message from pod']

Read more about specifying arguments to Rake tasks.

Can I add advertisements to my pod?

Sure, we have no rules that you cannot add advertisements to your diaspora* installation.

How do I define a Terms of Service document for signing up to my pod?

That feature is built in and we have a generic template that you are welcome to use. Of course, you can also edit it or create your own set of terms.

This feature is built in but not enabled by default. If you want to enable it, please add under settings in config/diaspora.toml the following and restart diaspora. If in doubt see config/diaspora.toml.example:

[configuration.settings.terms]

## First enable it by uncommenting below.
enable = true

When enabled, the footer and sidebar will have a link to terms page, and signup will have a disclaimer indicating that creating an account means the user accepts the terms of use.

While the project itself doesn't restrict what kind of terms pods run on, we realize not all podmins want to spend time writing them from scratch. Thus there is a basic ToS template included that will be used unless a custom one available.

To modify (or completely rewrite) the terms template, create a file called app/views/terms/terms.haml or app/views/terms/terms.erb and it will automatically replace the default template, which you can find at app/views/terms/default.haml.

There are also two configuration settings to customize the terms (when using the default template). These are optional.

• settings.terms.jurisdiction - indicate here in which country or state any legal disputes are handled.
• settings.terms.minimum_age - indicate here if you want to show a minimum required age for creating an account.

How do I modify the pod landing page?

Please see Custom_splash_page.

How can I delete spam from my pod?

To properly delete spam accounts and contents from your pod, no matter if the spam was created on your pod for federated to your pod, download this script, place it in your diaspora directory, read the comments, fill in the details, and run the script with RAILS_ENV=production bin/bundle exec ruby diaspora_spam.rb. If you have questions, please reach out to the project team on Discourse.

Errors and problems

What do I do about all these PGErrors, like disconnects and SSL problems?

If you are running diaspora* with PostgreSQL, beware that having the SSL setting turned on in the PostgreSQL config has been causing problems for several people. We recommend turning it off unless you know what you're doing.

My sidekiq is crashing, help!

Check your curl version

   /usr/bin/curl --version

Make sure you see AsynchDNS in the output. If this does not happen, check this issue on how to upgrade curl.

Check database connection pool

Make sure you have enough database pool connections to top your environment.sidekiq.concurrency. Search logs/sidekiq.log for errors relating to database connection not being available if unsure if you are running out. You can edit the pool setting in config/database.yml if needed and then restart. Make it sufficiently larger than your sidekiq concurrency*sidekiq workers, 1.5x is a safe rule here.

Check for out of open files errors

In the diaspora* app folder, do grep "Too many open files" log/sidekiq.log and check for results relating to the system user running the diaspora server running out of open files. If you get any errors, it is possible sidekiq can be brought down by the same problem. Follow for example this guide to increase the limit of open files available to the user running diaspora*.

Make sure memory is not running out

If the server runs out of memory, it is likely sidekiq will be the first to be killed. Check for Cannot allocate memory text in the ./script/server output, or use monitoring to see when memory goes critical. Increase the amount of swap available to make sure the application does not die (swap should be at least the same as RAM).

To make sure sidekiq doesn't use too much memory, make sure you are not running with too many Sidekiq workers or concurrency. On a small pod, you can safely but both values to 1 in config/diaspora.toml. Then restart and watch the Sidekiq admin panel and if a queue starts to build up, increase the concurrency in small increments until Sidekiq can handle the queue. There is NO need to run more Sidekiq concurrent threads than is needed to process the queue - you just use more memory this way!

What if my question isn't answered here?

Just ask us! Read more on how to do that at How we communicate.