Difference between revisions of "Notes On Installing and Running Diaspora"

From diaspora* project wiki
Jump to: navigation, search
(Add redis version requirement)
(Make this page somewhat usable again)
Line 15: Line 15:
 
# '''Running a common setup will get you the most help, if you need it.'''<br>Most people in the community will have some experience running Diaspora* with [http://unicorn.bogomips.org/ Unicorn] as the app server using [http://nginx.org/ Nginx] as outward-facing web server. Of course, you're free to run any other app server (Thin, Passenger...) or web server (Apache), but you might find it harder to get help if you run into unexpected troubles.
 
# '''Running a common setup will get you the most help, if you need it.'''<br>Most people in the community will have some experience running Diaspora* with [http://unicorn.bogomips.org/ Unicorn] as the app server using [http://nginx.org/ Nginx] as outward-facing web server. Of course, you're free to run any other app server (Thin, Passenger...) or web server (Apache), but you might find it harder to get help if you run into unexpected troubles.
 
# '''Diaspora* is developed utilizing latest web standards'''<br>Therefore UX is best with recent browsers, so please update your Firefox, Opera, Chrome or Safari to the newest version. We do not currently support any version of Internet Explorer, though we won't reject any [[Getting Started With Contributing|contributions attempting to change that]] circumstance.
 
# '''Diaspora* is developed utilizing latest web standards'''<br>Therefore UX is best with recent browsers, so please update your Firefox, Opera, Chrome or Safari to the newest version. We do not currently support any version of Internet Explorer, though we won't reject any [[Getting Started With Contributing|contributions attempting to change that]] circumstance.
# '''Diaspora* mandates HTTPS'''<br>as we encrypt communication amongst servers and to the client browsers. You can get a free SSL certificate from [http://www.startssl.com/ StartSSL]. You’ll need to reference the certificate in your webserver configuration file.
+
# '''Diaspora* strongly recommends HTTPS'''<br>as we encrypt communication amongst servers and to the client browsers. You can get a free SSL certificate from [http://www.startssl.com/ StartSSL]. You’ll need to reference the certificate in your webserver configuration file.
  
 
{{Note
 
{{Note
|'''The use of self-signed certificates is discouraged'''<br>While you can certainly get up and running with your own pod by using a self-signed SSL certificate, your pod may not be able to communicate with all other pods. It is therefore recommended that you use a certificate issued from a trusted Certificate Authority. Unfortunately, this also means that CaCert certificates won’t work. They are not (yet) part of most certificate bundles.}}
+
|'''The use of self-signed certificates is discouraged'''<br>While you can certainly get up and running with your own pod by using a self-signed SSL certificate, your pod may not be able to communicate with all other pods. It is therefore recommended that you use a certificate issued from a trusted Certificate Authority. Unfortunately, this also means that CACert certificates won’t work. They are not (yet) part of most certificate bundles.}}
  
 
=== Pointing out the obvious ===
 
=== Pointing out the obvious ===
Line 36: Line 36:
 
* [http://www.mysql.com MySQL] - Backend storage engine.
 
* [http://www.mysql.com MySQL] - Backend storage engine.
 
* Or: [http://www.postgresql.org/ PostgreSQL] - Backend storage engine.
 
* Or: [http://www.postgresql.org/ PostgreSQL] - Backend storage engine.
* [http://www.sqlite.org SQLite3] - Relational database management system
 
 
* [http://www.openssl.org/ OpenSSL] - An encryption library.
 
* [http://www.openssl.org/ OpenSSL] - An encryption library.
 
* [http://curl.haxx.se/ libcurl] - A library to make HTTP requests (and much more).
 
* [http://curl.haxx.se/ libcurl] - A library to make HTTP requests (and much more).
Line 68: Line 67:
  
 
=== Preparations ===
 
=== Preparations ===
Depending on the database you want to use, add either `DB="mysql"` for MySQL or `DB="postgres"` for PostgreSQL before each command starting with `bundle…`, or export the environment variable: `export DB="mysql"` for MySQL or `export DB="postgres"`. (If you want to have both database types available for easy switching, you can either skip this step or use `DB="all"`.)
+
Depending on the database you want to use, add either <tt>DB="mysql"</tt> for MySQL or <tt>DB="postgres"</tt> for PostgreSQL before each command starting with `bundle…`, or export the environment variable: `export DB="mysql"` for MySQL or `export DB="postgres"`. (If you want to have both database types available for easy switching use <tt>DB="all"</tt>.)
 +
 
 
=== Install Required Gems ===
 
=== Install Required Gems ===
 
To start the app server for the first time, you need to use Bundler to install
 
To start the app server for the first time, you need to use Bundler to install
Diaspora's gem depencencies.  Run (from Diaspora's root directory):
+
Diaspora's gem dependencies.  Run (from Diaspora's root directory):
  
<pre>bundle install --without development test heroku</pre>
+
<syntaxhighlight lang="bash">
 +
bundle install --without development test heroku
 +
</syntaxhighlight>
  
 
Bundler will also warn you if there is a new dependency and you
 
Bundler will also warn you if there is a new dependency and you
Line 80: Line 82:
 
NOTE: If you don't get a '''green success line''' at the end, double check if you've installed all dependencies. If you can't figure it out feel free to ask for help at the mailing list or the [[IRC Channel| How we use IRC]].
 
NOTE: If you don't get a '''green success line''' at the end, double check if you've installed all dependencies. If you can't figure it out feel free to ask for help at the mailing list or the [[IRC Channel| How we use IRC]].
  
NOTE: If you want to do any development run just `bundle install`
+
NOTE: If you want to do any development run just <tt>bundle install</tt>.
  
 
NOTE: If you are on Ruby 1.9.2 and get an error such as "invalid byte sequence in US-ASCII (ArgumentError)" then you need to set your system locale to UTF-8. [https://github.com/siefca/i18n-inflector/issues/3 This GitHub bug report] on the gem that causes the problem has steps for doing so on Ubuntu.
 
NOTE: If you are on Ruby 1.9.2 and get an error such as "invalid byte sequence in US-ASCII (ArgumentError)" then you need to set your system locale to UTF-8. [https://github.com/siefca/i18n-inflector/issues/3 This GitHub bug report] on the gem that causes the problem has steps for doing so on Ubuntu.
  
NOTE: If you get "Could not get Gemfile" make sure you are in the diaspora directory (`cd diaspora`) you just cloned.
+
NOTE: If you get "Could not get Gemfile" make sure you are in the diaspora directory (<tt>cd diaspora</tt>) you just cloned.
  
 
NOTE: If you do any other rails development on your machine, you will probably
 
NOTE: If you do any other rails development on your machine, you will probably
want to either run `bundle install --path vendor` instead to install the gems in your local diaspora
+
want to either run <tt>bundle install --path vendor</tt> instead to install the gems in your local diaspora
 
directory to avoid conflicts with your existing environment, or use an [https://rvm.beginrescueend.com RVM] gemset.
 
directory to avoid conflicts with your existing environment, or use an [https://rvm.beginrescueend.com RVM] gemset.
 +
 
=== Configure Diaspora ===
 
=== Configure Diaspora ===
Diaspora needs to know what host it's running on. Copy `config/diaspora.yml.example` to `config/diaspora.yml` <pre>cp config/diaspora.yml.example config/diaspora.yml</pre>, put your external url into the url field, section environment and make any other needed configuration changes.
+
Diaspora needs to know what host it's running on. Copy <tt>config/diaspora.yml.example</tt> to <tt>config/diaspora.yml</tt>
 +
 
 +
<syntaxhighlight lang="bash">
 +
cp config/diaspora.yml.example config/diaspora.yml
 +
</syntaxhighlight>
 +
 
 +
Now put your external URL into the url field in the environment section and make any other needed configuration changes.
  
 
=== Background ===
 
=== Background ===
Line 102: Line 111:
  
 
* Edit rails_environment in the server section in config/diaspora.yml
 
* Edit rails_environment in the server section in config/diaspora.yml
* Change the `environment.assets.serve` setting to `true` in the `config/diaspora.yml` file. With this setting enabled Diaspora can take advantage of Rails' ability to serve static content like images and .css files from the application's /public directory. However, Rails is not a webserver, so a better option would be to leave `environment.assets.serve` set to `false` and instead install a true webserver such as Apache or Nginx alongside Diaspora and modify that webserver’s configuration to serve the static content itself:
+
* You may change the <tt>environment.assets.serve</tt> setting to <tt>true</tt> in the <tt>config/diaspora.yml</tt> file. With this setting enabled Diaspora can take advantage of Rails' ability to serve static content like images and CSS files from the applications <tt>public/</tt> directory. However, Rails is not a webserver, so a better option would be to leave <tt>environment.assets.serve</tt> set to <tt>false</tt> and instead install a true webserver such as Apache or Nginx alongside Diaspora and modify that webserver’s configuration to serve the static content itself.
==== Apache 2 ====
 
<pre>
 
<VirtualHost *:80>
 
  ServerName diaspora.mydomain.com
 
  DocumentRoot /diaspora_root/public
 
  <Directory /diaspora_root/public>
 
      Allow from all
 
      Options -MultiViews
 
  </Directory>
 
</VirtualHost>
 
</pre>
 
  
For a more advanced configuration have a look at [https://gist.github.com/719014 this Gist].
+
==== Example webserver configurations ===
  
'''OSX Server Note:''' If you wish to use Apache built into OSX Server, use Server Admin to create a site on port 443. A file should be created in the directory `/etc/apache2/sites/` with a name like "000X_any_443_domain.com.conf".  The above proxy settings will allow you to continue to use your existing web services alongside the Diaspora installation.
+
* [https://gist.github.com/MrZYX/719014 Apache]
 +
* [https://gist.github.com/MrZYX/1355430 Nginx]
 +
* [[Using lighttpd as webserver]]
  
==== Nginx ====
+
'''OSX Server Note:''' If you wish to use Apache built into OSX Server, use Server Admin to create a site on port 443.  A file should be created in the directory <tt>/etc/apache2/sites/</tt> with a name like "000X_any_443_domain.com.conf".  The above proxy settings will allow you to continue to use your existing web services alongside the Diaspora installation.
Get inspired by our [[Nginx Configuration]].
 
==== lighttpd ====
 
  
See [[Using lighttpd as webserver]] for an example configuration.
+
'''NOTE:''' If you are serving through a reverse proxy, you will need to set the <tt>X_FORWARDED_PROTO</tt> header to <tt>https</tt> on your reverse proxy server.  The Nginx and Apache example configurations show how to do this.  Failure to set this header will lead to a redirect loop.
  
=== Configuring SSL ===
+
'''Different certificates''' Make sure that your top level domain (e.g. example.com if your pod is pod.example.com) hands out the _same_ certificate as your actual pod URL. The communication with other pods running on old systems might not work otherwise.
As noted previously, you will need to configure NGINX to point to your SSL certificate (procured from either [http://startssl.com StartSSL] or [http://www.sslshopper.com elsewhere].  
 
  
'''NOTE:''' Certificates issued from StartSSL will probably also require that the StartSSL intermediate certificate be concatenated in order for some pods to communicate properly. The following link will help you create a properly concatenated certificate for use by NGINX: [http://blog.dembowski.net/2010/02/25/startssl-and-nginx/ StartSSL and NGINX]
+
=== Set up the database ===
  
'''NOTE:''' If you are serving through a reverse proxy, you will need to set the `X_FORWARDED_PROTO` header to `https` on your reverse proxy serverThe NGINX and Apache example configurations show how to do this.  Failure to set this header will lead to a redirect loop.
+
'''Note for PostgreSQL users:''' If you are running Diaspora with PostgreSQL, beware that having [http://www.postgresql.org/docs/9.1/interactive/runtime-config-connection.html#GUC-SSL the ssl setting] turned on in the PostgreSQL config has been causing problems for several peopleWe recommend turning it off unless you know what you're doing.
  
Take note: We upgrade all port 80 requests to port 443. We recommend that you do the same.
+
You need to configure the database settings. Copy <tt>config/database.yml.example</tt> to <tt>config/database.yml</tt> and edit it:
  
 +
<syntaxhighlight lang="bash">
 +
cp config/database.yml.example config/database.yml
 +
</syntaxhighlight>
  
'''OSX Server Note:''' If you use startssl to obtain both a private key and a certificate don't forget to decrypt the private key using the following command `openssl rsa -in ssl.key -out ssl.key`.  Import the decrypted key (ssl.key) and a certificate (ssl.crt) file into Server Admin by dragging the files into the Certificate manager found here: Server Admin>Web>Site>example.com>Security>Manage Certificates>Import Certificate Identity.  If the certificate & key are valid the certificate should be 'blue'.  Once imported, the certificate can then be selected as the security for the site.
 
  
'''Different certificates''' Make sure that your top level domain (e.g. example.com if your pod is pod.example.com) hands out the _same_ certificate as your actual pod URL. The communication with other pods (or applications, like [http://www.cubbi.es cubbi.es] might not work otherwise.
+
After that, run <syntaxhighlight lang="bash">bundle exec rake db:create</syntaxhighlight> for development mode or  
 
+
<syntaxhighlight lang="bash">RAILS_ENV=production bundle exec rake db:create</syntaxhighlight> for production mode
=== Set up the database ===
 
 
 
'''Note for PostgreSQL users:''' If you are running Diaspora with PostgreSQL, beware that having [http://www.postgresql.org/docs/9.1/interactive/runtime-config-connection.html#GUC-SSL 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.
 
 
 
You need to configure the database settings. Copy config/database.yml.example to config/database.yml <pre>cp config/database.yml.example config/database.yml</pre>
 
and edit it properly.
 
 
 
After that, run <pre>bundle exec rake db:create</pre> for development mode or  
 
<pre>RAILS_ENV=production bundle exec rake db:create</pre> for production mode
 
 
to create the needed database (or you could instead create the database manually.)  
 
to create the needed database (or you could instead create the database manually.)  
 
If you want to create it manually make sure you choose utf8 as charset and utf8_bin as collation.
 
If you want to create it manually make sure you choose utf8 as charset and utf8_bin as collation.
  
 
Now you need to create the necessary tables. To do so run  
 
Now you need to create the necessary tables. To do so run  
<pre>bundle exec rake db:schema:load</pre> for development mode or
+
<syntaxhighlight lang="bash">bundle exec rake db:schema:load</syntaxhighlight> for development mode or
<pre>RAILS_ENV=production bundle exec rake db:schema:load</pre> for production mode.
+
<syntaxhighlight lang="bash">RAILS_ENV=production bundle exec rake db:schema:load</syntaxhighlight> for production mode.
'''Warning:''' This will empty your database, on update use `db:migrate` instead of `db:schema:load`!
+
'''Warning:''' This will empty your database, on update use <tt>db:migrate</tt> instead of <tt>db:schema:load</tt>!
  
 
=== Set up services ===
 
=== Set up services ===
Line 162: Line 152:
 
== Running Diaspora ==
 
== Running Diaspora ==
  
To turn on the server use the command `./script/server` from the working directory.  
+
To turn on the server use the command <tt>./script/server</tt> from the working directory.  
  
This will start Unicorn and Resque workers. The application is then available at http://your_pod:3000. You can change the port by either editing server.port in config/diaspora.yml or by setting up a reverse proxy (see above) if you want to run Diaspora at a subdomain or use HTTPS more easily.
+
This will start Unicorn and the Sidekiq workers. The application is then available at http://your_pod:3000. You can change the port by either editing <tt>server.port</tt> in <tt>config/diaspora.yml</tt> or by setting up a reverse proxy (see above) if you want to run Diaspora at a subdomain or use HTTPS more easily.
  
 
Note: Ensure your database servers (Redis and MySQL or PostgreSQL) are running before trying to start the server.
 
Note: Ensure your database servers (Redis and MySQL or PostgreSQL) are running before trying to start the server.
Line 170: Line 160:
 
Once Diaspora is running, just open it up in a web browser and sign up for an account.   
 
Once Diaspora is running, just open it up in a web browser and sign up for an account.   
  
'''Note:''' If you are running a 'production' installation and requests to the /assets directory return a HTTP 404 error to your client, run `RAILS_ENV=production DB="mysql" bundle exec rake assets:precompile` for MySQL or `RAILS_ENV=production DB="postgres" bundle exec rake assets:precompile` for PostgreSQL after each git pull. If you get a 500 page installation try restarting Diaspora after that.
+
'''Note:''' If you are running a 'production' installation and requests to the /assets directory return a HTTP 404 error to your client, run <tt>bundle exec rake assets:precompile</tt> after each git pull. If you get a 500 page installation try restarting Diaspora after that.
  
'''Note:''' If you are running a 'production' installation and you do not see any images hosted, but the content loads fine, ensure that your reverse proxy is serving them. If you sure you don't want to setup a reverse proxy ensure that you have set your `environment.assets.serve` setting turned to `true` everywhere in your `diaspora.yml`.
+
'''Note:''' If you are running a 'production' installation and you do not see any images hosted, but the content loads fine, ensure that your reverse proxy is serving them. If you sure you don't want to setup a reverse proxy ensure that you have set your <tt>environment.assets.serve</tt> setting turned to <tt>true</tt> everywhere in your <tt>diaspora.yml</tt>.
  
 
== Updating Diaspora ==
 
== Updating Diaspora ==
Line 180: Line 170:
 
Change into the Diaspora root folder and run
 
Change into the Diaspora root folder and run
  
<pre>git pull origin master</pre>
+
<syntaxhighlight lang="bash">
 +
git pull origin master
 +
</syntaxhighlight>
  
 
If the update changes the Gemfile or Gemfile.lock files, for MySQL run
 
If the update changes the Gemfile or Gemfile.lock files, for MySQL run
  
<pre>DB="mysql" bundle install --without development test heroku</pre>
+
<syntaxhighlight lang="bash">
 +
DB="mysql" bundle install --without development test heroku
 +
</syntaxhighlight>
  
 
or for PostgreSQL:
 
or for PostgreSQL:
  
<pre>DB="postgres" bundle install --without development test heroku</pre>
+
<syntaxhighlight lang="bash">
 +
DB="postgres" bundle install --without development test heroku
 +
</syntaxhighlight>
  
 
Now kill your running Diaspora instance.
 
Now kill your running Diaspora instance.
Line 194: Line 190:
 
In order to apply any new schema always run
 
In order to apply any new schema always run
  
<pre>DB="mysql" bundle exec rake db:migrate</pre>
+
<syntaxhighlight lang="bash">
 +
DB="mysql" bundle exec rake db:migrate
 +
</syntaxhighlight>
  
 
for MySQL, or
 
for MySQL, or
  
<pre>DB="postgres" bundle exec rake db:migrate</pre>
+
<syntaxhighlight lang="bash">
 +
DB="postgres" bundle exec rake db:migrate
 +
</syntaxhighlight>
  
 
for PostgreSQL.
 
for PostgreSQL.
Line 204: Line 204:
 
Or if you you run in production mode
 
Or if you you run in production mode
  
<pre>RAILS_ENV="production" DB="mysql" bundle exec rake db:migrate</pre>
+
<syntaxhighlight lang="bash">
 +
RAILS_ENV="production" DB="mysql" bundle exec rake db:migrate
 +
</syntaxhighlight>
  
 
for MySQL, or
 
for MySQL, or
  
<pre>RAILS_ENV="production" DB="postgres" bundle exec rake db:migrate</pre>
+
<syntaxhighlight lang="bash">
 +
RAILS_ENV="production" DB="postgres" bundle exec rake db:migrate
 +
</syntaxhighlight>
  
 
for PostgreSQL.
 
for PostgreSQL.
Line 216: Line 220:
 
After each update run:
 
After each update run:
  
<pre>DB="mysql" bundle exec rake assets:precompile / DB="postgresql" bundle exec rake assets:precompile</pre>
+
<syntaxhighlight lang="bash">
 +
bundle exec rake assets:precompile
 +
</syntaxhighlight>
  
 
== Appendix ==
 
== Appendix ==
Line 223: Line 229:
  
 
Diaspora’s test suite uses [http://rspec.info/ Rspec], a behavior driven testing framework. To run all tests execute: `rake`. Note that some of our tests require a display to be attached; if you just want to run the command-line tests, do `rake spec`.
 
Diaspora’s test suite uses [http://rspec.info/ Rspec], a behavior driven testing framework. To run all tests execute: `rake`. Note that some of our tests require a display to be attached; if you just want to run the command-line tests, do `rake spec`.
=== Read-Only Installation ===
 
The directories 'tmp', 'public/uploads' and 'log' must be writable by the user running Diaspora even in a read-only installation.
 
 
Some of Diaspora's web content in the public/ folder  is generated at runtime. In order to create a read-only installation, this content must be generated at install time instead.
 
 
Run sass/haml and create e. g.,  public/stylesheets/{application,ui,sessions}.css:
 
<pre>
 
bundle exec thin -d --pid log/thin.pid start
 
wget http://localhost:3000; rm index.html
 
bundle exec thin --pid log/thin.pid stop
 
</pre>
 
 
Precache public/assets/*gz files:
 
<pre>bundle exec rake assets:precompile</pre>
 
After these commands  also the *public/* folder  can be read-only (although *public/uploads* need to be writable, see above).
 
  
 
[[Category:Podmin]]
 
[[Category:Podmin]]
 
[[Category:Installation]]
 
[[Category:Installation]]

Revision as of 06:48, 13 June 2013

»» Note
If you just want to use (or try out) Diaspora*, you don't necessarily have to set up your own pod.
You can join a pod that has registrations enabled, running the Diaspora* software. Just pick one from the list of community-operated servers that seems best to you.
If you still want to run your own pod... we salute you. Read on.


Introduction

Diaspora* is run on a network of connected servers, or "pods". This document contains technical information for installing the necessary software to run a pod yourself, either for development, or as a new pod on the Diaspora network.

A little knowledge on administrating Unix-like systems (Linux, MacOS) or experience setting up other Rails applications can't hurt in this endeavour... ;)

For OS-Specific and service-specific guides, check out this page.

Things to Know

  1. The install is a bit complex, but we're here to help
    If you run into problems, please visit us in our IRC channels on Freenode.
  2. Running a common setup will get you the most help, if you need it.
    Most people in the community will have some experience running Diaspora* with Unicorn as the app server using Nginx as outward-facing web server. Of course, you're free to run any other app server (Thin, Passenger...) or web server (Apache), but you might find it harder to get help if you run into unexpected troubles.
  3. Diaspora* is developed utilizing latest web standards
    Therefore UX is best with recent browsers, so please update your Firefox, Opera, Chrome or Safari to the newest version. We do not currently support any version of Internet Explorer, though we won't reject any contributions attempting to change that circumstance.
  4. Diaspora* strongly recommends HTTPS
    as we encrypt communication amongst servers and to the client browsers. You can get a free SSL certificate from StartSSL. You’ll need to reference the certificate in your webserver configuration file.
»» Note
The use of self-signed certificates is discouraged
While you can certainly get up and running with your own pod by using a self-signed SSL certificate, your pod may not be able to communicate with all other pods. It is therefore recommended that you use a certificate issued from a trusted Certificate Authority. Unfortunately, this also means that CACert certificates won’t work. They are not (yet) part of most certificate bundles.


Pointing out the obvious

»» Important
Do not run anything as root if it's not explicitly requested by this guide.
Just use your normal user - or even better - create a separate user for Diaspora*.


We frequently see people doing everything as root. If you think that's a good idea: It's not. It's the worst thing you can do! Not only is it a security risk, it also violates all sorts of best-practices. See this comment for a short rationale on that topic.

Preparing your system

In order to run Diaspora*, you will need to install the following dependencies:

  • Build tools - Packages needed to compile the components that follow.
  • Ruby - The Ruby programming language.
    (We’re developing mostly on 1.9.3 and support for 1.8.7 was dropped a while ago.)
  • RubyGems - A package manager for Ruby code that we use to download libraries (“gems”) that Diaspora uses.
  • Bundler - A gem management tool for Ruby projects.
  • MySQL - Backend storage engine.
  • Or: PostgreSQL - Backend storage engine.
  • OpenSSL - An encryption library.
  • libcurl - A library to make HTTP requests (and much more).
  • ImageMagick - An image processing library we use to resize uploaded photos.
  • Git - A version control system, which you will need to download the Diaspora source code from GitHub.
  • Redis 2.0 or later - A persistent key-value store that we use via Sidekiq for background job processing.
  • one of the JavaScript runtimes on execjs' supported list.
»» Note
For operating-system and hosting-service specific guides, check out this list of instructions.
After all the requirements are installed on your system, return to this page and proceed with the installation.


Installing Diaspora*

Getting Diaspora* Source

Our source code is hosted at GitHub. We produce tagged stable releases, and on the master branch you will always find the code for the most recent release. If you have never used GitHub before, their help desk has a pretty awesome guide for getting set up.

To get a copy of the Diaspora* source from the master branch, use the following command:

git clone -b master git://github.com/diaspora/diaspora.git && cd diaspora

This will copy all files from the repository into a diaspora folder under the current directory.

If you already cloned the repository get sure to checkout the master branch with (in the diaspora dir):

git checkout master

Preparations

Depending on the database you want to use, add either DB="mysql" for MySQL or DB="postgres" for PostgreSQL before each command starting with `bundle…`, or export the environment variable: `export DB="mysql"` for MySQL or `export DB="postgres"`. (If you want to have both database types available for easy switching use DB="all".)

Install Required Gems

To start the app server for the first time, you need to use Bundler to install Diaspora's gem dependencies. Run (from Diaspora's root directory):

bundle install --without development test heroku

Bundler will also warn you if there is a new dependency and you need to bundle install again.

NOTE: If you don't get a green success line at the end, double check if you've installed all dependencies. If you can't figure it out feel free to ask for help at the mailing list or the How we use IRC.

NOTE: If you want to do any development run just bundle install.

NOTE: If you are on Ruby 1.9.2 and get an error such as "invalid byte sequence in US-ASCII (ArgumentError)" then you need to set your system locale to UTF-8. This GitHub bug report on the gem that causes the problem has steps for doing so on Ubuntu.

NOTE: If you get "Could not get Gemfile" make sure you are in the diaspora directory (cd diaspora) you just cloned.

NOTE: If you do any other rails development on your machine, you will probably want to either run bundle install --path vendor instead to install the gems in your local diaspora directory to avoid conflicts with your existing environment, or use an RVM gemset.

Configure Diaspora

Diaspora needs to know what host it's running on. Copy config/diaspora.yml.example to config/diaspora.yml

cp config/diaspora.yml.example config/diaspora.yml

Now put your external URL into the url field in the environment section and make any other needed configuration changes.

Background

Diaspora is a Rails-app and as such it has different running modes. The default is "development mode" in which some performance features such as source code caching are disabled. The other mode is "production mode" which is best for actually running a pod. If you want just a test installation to develop for Diaspora, keep the defaults. However, if you plan to actually host a pod choose production mode.

If you want to run production mode:

  • Edit rails_environment in the server section in config/diaspora.yml
  • You may change the environment.assets.serve setting to true in the config/diaspora.yml file. With this setting enabled Diaspora can take advantage of Rails' ability to serve static content like images and CSS files from the applications public/ directory. However, Rails is not a webserver, so a better option would be to leave environment.assets.serve set to false and instead install a true webserver such as Apache or Nginx alongside Diaspora and modify that webserver’s configuration to serve the static content itself.

= Example webserver configurations

OSX Server Note: If you wish to use Apache built into OSX Server, use Server Admin to create a site on port 443. A file should be created in the directory /etc/apache2/sites/ with a name like "000X_any_443_domain.com.conf". The above proxy settings will allow you to continue to use your existing web services alongside the Diaspora installation.

NOTE: If you are serving through a reverse proxy, you will need to set the X_FORWARDED_PROTO header to https on your reverse proxy server. The Nginx and Apache example configurations show how to do this. Failure to set this header will lead to a redirect loop.

Different certificates Make sure that your top level domain (e.g. example.com if your pod is pod.example.com) hands out the _same_ certificate as your actual pod URL. The communication with other pods running on old systems might not work otherwise.

Set up the database

Note for PostgreSQL users: 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.

You need to configure the database settings. Copy config/database.yml.example to config/database.yml and edit it:

cp config/database.yml.example config/database.yml


After that, run

bundle exec rake db:create

for development mode or

RAILS_ENV=production bundle exec rake db:create

for production mode

to create the needed database (or you could instead create the database manually.) If you want to create it manually make sure you choose utf8 as charset and utf8_bin as collation.

Now you need to create the necessary tables. To do so run

bundle exec rake db:schema:load

for development mode or

RAILS_ENV=production bundle exec rake db:schema:load

for production mode.

Warning: This will empty your database, on update use db:migrate instead of db:schema:load!

Set up services

If you want to connect your pod to other services like Twitter, Tumblr or Facebook read instructions integrating other Social Networks.

Running Diaspora

To turn on the server use the command ./script/server from the working directory.

This will start Unicorn and the Sidekiq workers. The application is then available at http://your_pod:3000. You can change the port by either editing server.port in config/diaspora.yml or by setting up a reverse proxy (see above) if you want to run Diaspora at a subdomain or use HTTPS more easily.

Note: Ensure your database servers (Redis and MySQL or PostgreSQL) are running before trying to start the server.

Once Diaspora is running, just open it up in a web browser and sign up for an account.

Note: If you are running a 'production' installation and requests to the /assets directory return a HTTP 404 error to your client, run bundle exec rake assets:precompile after each git pull. If you get a 500 page installation try restarting Diaspora after that.

Note: If you are running a 'production' installation and you do not see any images hosted, but the content loads fine, ensure that your reverse proxy is serving them. If you sure you don't want to setup a reverse proxy ensure that you have set your environment.assets.serve setting turned to true everywhere in your diaspora.yml.

Updating Diaspora

Read the Changelog!

Change into the Diaspora root folder and run

git pull origin master

If the update changes the Gemfile or Gemfile.lock files, for MySQL run

DB="mysql" bundle install --without development test heroku

or for PostgreSQL:

DB="postgres" bundle install --without development test heroku

Now kill your running Diaspora instance.

In order to apply any new schema always run

DB="mysql" bundle exec rake db:migrate

for MySQL, or

DB="postgres" bundle exec rake db:migrate

for PostgreSQL.

Or if you you run in production mode

RAILS_ENV="production" DB="mysql" bundle exec rake db:migrate

for MySQL, or

RAILS_ENV="production" DB="postgres" bundle exec rake db:migrate

for PostgreSQL.

Now start Diaspora again.

After each update run:

bundle exec rake assets:precompile

Appendix

Testing

Normally you don't need this if you aren't developing for Diaspora, just skip it :)

Diaspora’s test suite uses Rspec, a behavior driven testing framework. To run all tests execute: `rake`. Note that some of our tests require a display to be attached; if you just want to run the command-line tests, do `rake spec`.