This article is a work in progress, it may contain incomplete or inaccurate information. There may be additional information on the talk page.
This guide still needs to be rewritten for the the installation guides form
- 1 Caveat
- 2 Versions
- 3 Package Management
- 4 Prerequisites
- 5 Building Required Packages
- 6 Setting up your Diaspora* User
- 7 Setting up your Gems correctly
- 8 Completing your installation
This guide is intended for experienced FreeBSD administrators. It is not intended as an introduction to FreeBSD. It uses a combination of ports and packages and takes a while to get everything compiled and running properly.
Note that while this guide applies to multiple versions, behaviors and performance on 10.0-RELEASE may be different as a result of changing the system compiler from GNU gcc to LLVM clang.
These instructions apply to FreeBSD 9.2-RELEASE and 10.0-RELEASE. It is generally not recommended to run Diaspora* on versions prior to these as they have either reached or will reach end of life in the foreseeable future.
Use of the `portmaster` ports management tool is recommended. Use of pkgng is required for consistency. pkg_* is obsoleted and should not be used for new installs.
You should run
pkg followed by
pkg2ng and set up
/etc/make.conf before installing
It is assumed that you have a fresh install of FreeBSD, using portsnap for ports tree management. You will also need a non-root user that will own the Diaspora* installation and processes.
It is vitally important that you do not use tabs in make.conf. This will break your system! The settings here are in addition to any others you already have, and are required to prevent conflicts.
WITH_PKGNG=yes WITHOUT="X11" OPTIONS_UNSET=X11 # DO NOT USE SPACES OR COMMENTS IN THE FOLLOWING LINE EVER! DEFAULT_VERSIONS= perl5=5.16 ruby=2.1 python=2.7 postgresql=9.3 mysql=5.5 PERL5_DEFAULT=5.16 RUBY_VER=2.1 WANT_PGSQL_VER=93 WANT_MYSQL_VER=55 # 55m for MariaDB, 55p for Percona
Prerequisite Packages for Building
The following packages will be required before you begin building Diaspora* on FreeBSD:
The following packages are optional but recommended before you begin building Diaspora* on FreeBSD:
Note that you may choose to use
security/openssl instead of the system OpenSSL. However, this must be built first and most packages will NOT use it.
You should select
CURL support for
devel/git. This will pull in the
ftp/curl dependency. The
ETCSYMLINK option in ca_root_nss is optional and not required.
devel/git will always pull in Python.
You can use other versions of Python, but 2.7 is the recommended version for most installations. If you will be running other software that depends on Python, use the version most appropriate for that software - usually 2.7 anyways.
Python should use the default options unless other software requires you to set additional options.
Building Required Packages
The complete list of required packages (which will automatically pull in related dependencies) is as follows. Again note that this is not a comprehensive list of installed packages, but rather the packages you must have, in the order required to pull in all of the required dependencies.
lang/ruby20matching what you set in make.conf!
PostgreSQL will always offer the best performance on FreeBSD, especially on multi-core systems. 9.3 offers significant performance benefits over prior versions as well.
You will need to install:
Optionally, you may also want to install:
As tempting as it may be, do NOT install PL/Ruby. It has not been maintained for years and contains significant security vulnerabilities which will result in the compromise of your pod.
The only mandatory options are
INTDATE, NLS, SSL, TZDATA, and
XML which are set by default.
OPTIMIZED_CFLAGS is optional but not recommended on 10.0-RELEASE systems at this time.
It is very important to note that there are two ImageMagick 'base' ports, both of which will pull in many many dependencies. Only ever use
graphics/ImageMagick-nox11. It is strongly recommended that you use portmaster to build ImageMagick locally, as the default packages will pull in numerous dependencies which you do not need for Diaspora*.
It is recommended that you set only these options:
This will minimize the number of dependencies which are pulled in. Do not select both
JPEG as this will cause the build to fail.
THREADS introduces no additional dependencies and will offer faster performance on most systems.
Other options which you may wish to set, but are entirely optional:
Note that ImageMagick has a very ugly, nasty, long dependency chain so it is in your best interests to try and minimize it. You should always include
PERL, since this will only pull in PCRE - a required package - if it is missing.
Unfortunately, this package is unavoidable, and will take you longer to set the options on than it takes to build. Do NOT install ghostscript9-nox11 using pkg as this will pull in over 50MB of pointless dependencies! The FreeBSD package builder uses default options, which means CUPS and every single driver.
The ONLY options you should leave set in ghostscript9-nox11 are:
- GS_jpeg, GS_jpeggray
- GS_bit, GS_bitrgb, GS_bitcmyk
GS_pngmono, GS_pnggray, GS_png16, GS_png256, GS_png16m, GS_pngalpha, GS_png48
Absolutely all other options should be unset, unless you have a specific reason to include them. You must include GS_plan or the build will fail.
databases/redis, you should select the
LUA option only if you plan to use Lua for other things.
Do not select
LUAJIT. This will break things.
This is where things get slightly interesting.For this installation, we will presume Ruby 2.1 - however, you can use Ruby 2.0 simply by changing "2.1" to "2.0" in
Note that you can install multiple Ruby versions without causing conflicts! This is by design! If you do not set up
make.conf correctly, you will have gem version conflicts which will break your installation!
The Ruby port will pull in
libyaml, libffi, and
libexecinfo if they are missing.
IMPORTANT TEMPORARY WORKAROUND
Your Ruby build will fail out of the box currently (April 2014) on all versions! You must edit
lang/ruby21/Makefile and change:
Ruby Gems Bundler
You should not use Ruby to install Bundler unless you are installing it locally. Instead, you should use
sysutils/rubygem-bundler to provide a system-wide Bundler install.
You should not install bundle dependencies using ports. This will put you out of sync with Diaspora* recommended/required versions. Only install
Node.js does not jump out at most people because of the way it is set up in ports. You are looking for
If you require Node Package Manager, you should install
www/npm - however, this is optional as Diaspora* does not require NPM.
Setting up your Diaspora* User
To make life easier for yourself, you should set your Diaspora* environment variables in the shell rc for your shell of choice. Here are some examples:
csh (FreeBSD default)
setenv RAILS_ENV production setenv DB postgres
bash (optional package)
export RAILS_ENV='production' export DB='postgres'
ksh93 (optional package)
RAILS_ENV=production DB=postgres export RAILS_ENV DB
Setting up your Gems correctly
Because FreeBSD ports are always "current", it is guaranteed that you will have version mismatches if you use ports. Similarly, if you install system-wide from gems, you will conflict with ports - often in ways that break Ruby! Therefore, you must _never_ install your Gems system-wide or from ports!
Instead, you should install your Gems under your Diaspora* user's installation to prevent any problems and ensure you have the correct versions.
root@myhost # su - diaspora diaspora@myhost $ cd ~/diasporaInstallDir/ diaspora@myhost ~/diasporaInstallDir/ $ bundle install --without test development --path vendor/bundle
--path vendor/bundle will install your Gems to diasporaInstallDir/vendor/bundle.
ERROR: no content specified!
Congrats! You have all your dependencies installed.
Completing your installation
Get the source
It's time to download diaspora*! As your diaspora user run:
cd ~ git clone https://github.com/diaspora/diaspora.git cd diaspora
Don't miss the cd diaspora, all coming commands expect to be run from that directory!
cp config/database.yml.example config/database.yml cp config/diaspora.yml.example config/diaspora.yml
It's time to install the Ruby libraries required by diaspora*:
gem install bundler script/configure_bundler bin/bundle install --full-index
This takes quite a while. When it's finished, you should see a message similar to: Bundle complete! 137 Gemfile dependencies, 259 gems now installed. If that's not the case, you should seek for help on the mailing list or the IRC channel.
Running the manual gem install command shown in the error message can sometimes show a clearer error message if the bundle command fails.
Double check your config/database.yml looks right and run:
bundle exec rake db:create db:migrate
It's time to start diaspora*:
Your diaspora server is now running, either on a unix socket (current default) or on http port 3000. The listening method can be configured in diaspora.yml, search for '3000' or 'listen' to find the correct line.
You will likely need to install a reverse proxy (example on github for apache2) in order to get it to be served publicly. If you are new to running rails applications you may find the diaspora components page helpful for orientation.
You have to do backups of your pod data. If you lose your data, you won't be able to use the combination of your old username and old domain ever again. Make sure to store the backups on a different server, or at least on a different hard drive.
For details on how to do backups, see Pod data backup.