Difference between revisions of "Installation/FreeBSD"

From diaspora* project wiki
Jump to: navigation, search
(Major major overhaul and update for FreeBSD 9.2/10.0, options information, etcetera.)
Line 4: Line 4:
 
=== Caveat ===
 
=== Caveat ===
  
Installation on FreeBSD is a more involved and variable process than on some (all?) of the Linux distros.  This guide is intended for experienced FreeBSD admins. It uses a combination of ports and packages and takes a while to get everything compiled and running properly.
+
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.
  
This is not intended as in introduction to FreeBSD.
+
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.
  
 
== Versions ==
 
== Versions ==
  
These instructions are for installing Diaspora* on a fresh install of FreeBSD 9.0.
+
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.
  
They will install Ruby 1.9 and PostgreSQL 9.1.
+
== Package Management ==
  
== Package Management ==
+
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.
  
Use of the `portmaster` ports management tool is assumed.
+
You should run <code>pkg</code> followed by <code>pkg2ng</code> and set up <code>/etc/make.conf</code> before installing <code>ports-mgmt/portmaster</code>.  
  
 
== Prerequisites ==
 
== Prerequisites ==
  
It is assumed that you have a fresh install of FreeBSD 9.0 with ports tree installed and you are running from the non-root user that you intend to run Diaspora* under.   
+
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.   
 +
 
 +
=== make.conf ===
 +
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.
 +
<code><pre>
 +
WITH_PKGNG=yes
 +
WITHOUT="X11"
 +
OPTIONS_UNSET=X11
  
Packages/ports up and running should include:
+
# DO NOT USE SPACES OR COMMENTS IN THE FOLLOWING LINE EVER!
* bash
+
DEFAULT_VERSIONS=    perl5=5.16 ruby=2.1 python=2.7 postgresql=9.3 mysql=5.5
* sudo
 
* curl
 
* ca_nss_root
 
  
== The Basics ==
+
PERL5_DEFAULT=5.16
 +
RUBY_VER=2.1
 +
WANT_PGSQL_VER=93
 +
WANT_MYSQL_VER=55    # 55m for MariaDB, 55p for Percona
 +
</pre></code>
  
Install required libraries:
+
=== Prerequisite Packages for Building ===
<pre>sudo pkg_add -r libxml2 libxslt</pre>
+
The following packages will be '''required''' before you begin building Diaspora* on FreeBSD:
 +
* ports-mgmt/portmaster
 +
* security/ca_root_nss
 +
* devel/git
  
 +
You should select <code>CURL</code> support for <code>devel/git</code>. This will pull in the <code>ftp/curl</code> dependency. The <code>ETCSYMLINK</code> option in ca_root_nss is optional and not required.
 +
 +
The following packages are optional but ''recommended'' before you begin building Diaspora* on FreeBSD:
 +
* shells/bash
 +
* security/sudo
 +
 +
= 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.
 +
* <code>databases/postgresql93-server
 +
* graphics/ImageMagick-nox11
 +
* databases/sqlite3
 +
* databases/redis
 +
* lang/ruby21</code> OR <code>lang/ruby20</code> matching what you set in make.conf!
 +
* <code>sysutils/rubygem-bundler
 +
* www/node</code>
  
 
== PostgreSQL ==
 
== PostgreSQL ==
 +
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.
  
To install Postgresql as your database, run the following:
+
You will need to install:
<pre>sudo pkg_add -r postgresql91-server</pre>
+
* databases/postgresql93-server
+
Optionally, you may also want to install:
Add `postgresql_enable="YES"` to /etc/rc.conf, then:
+
* databases/postgresql93-contrib
  
        sudo /usr/local/etc/postgresql initdb
+
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.
        sudo /usr/local/etc/postgresql start
 
   
 
Set it up to run as your user (diaspora for example):
 
  
        sudo su pgsql
+
=== Options: databases/postgresql93-server ===
        createuser -srdP diaspora
+
The only mandatory options are <code>INTDATE, NLS, SSL, TZDATA</code>, and <code>XML</code> which are set by default.
        exit
+
 
 +
<code>OPTIMIZED_CFLAGS</code> is optional but not recommended on 10.0-RELEASE systems at this time.
  
 
== ImageMagick ==
 
== ImageMagick ==
 +
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''' <code>graphics/ImageMagick-nox11</code>. 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*.
  
To install ImageMagick, run the following:
+
=== Options: graphics/ImageMagick-nox11 ===
 +
It is recommended that you set only these options:
 +
* <code>16BIT_PIXEL
 +
* BZIP2
 +
* FONTCONFIG
 +
* FREETYPE
 +
* JPEG
 +
* LQR
 +
* LZMA
 +
* MODULES
 +
* PERL
 +
* PNG
 +
* THREADS
 +
* TIFF</code>
 +
This will minimize the number of dependencies which are pulled in. Do not select both <code>JASPER</code> and <code>JPEG</code> as this will cause the build to fail. <code>THREADS</code> introduces no additional dependencies and will offer faster performance on most systems.
  
        sudo pkg_add -r ImageMagick-nox11
+
Other options which you may wish to set, but are entirely optional:
 +
* <code>DOCS
 +
* FFTW
 +
* GRAPHVIZ
 +
* HDRI
 +
* OPENEXR</code>
  
== SQLite3 ==
+
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 <code>PERL</code>, since this will only pull in PCRE - a required package - if it is missing.
  
To install sqlite3, run the following:
+
=== Options: print/ghostscript9-nox11 ===
 +
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.
  
        sudo pkg_add -r sqlite3
+
The ONLY options you should leave set in ghostscript9-nox11 are:
 +
* <code>FONTCONFIG
 +
* ICONV
 +
* GS_jpeg, GS_jpeggray
 +
* GS_bit, GS_bitrgb, GS_bitcmyk
 +
* GS_plan
 +
* GS_pngmono, GS_pnggray, GS_png16, GS_png256, GS_png16m, GS_pngalpha, GS_png48</code>
  
== Git ==
+
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.
  
To install Git, run the following:
+
== SQLite3 ==
 +
You should always use <code>databases/sqlite3</code> rather than relying on any built-ins. SQLite3 is true to its name and pulls in essentially no dependencies.
  
        sudo pkg_add -r git
+
You should generally use the default options. On busy pods or systems with lots of memory, you may wish to select <code>TS2</code> - Memory by default - over the default of <code>TS1</code>. However you should only do this if you really know what you're doing!
  
 
== Redis ==
 
== Redis ==
 +
When building <code>databases/redis</code>, you should select the <code>LUA</code> option only if you plan to use Lua for other things.
 +
Do '''not''' select <code>LUAJIT</code>. This will break things.
 +
 +
== Ruby ==
 +
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 <code>/etc/make.conf</code>.
 +
 +
'''Note that you can install multiple Ruby versions ''without'' causing conflicts! This is by design!''' If you do not set up <code>make.conf</code> correctly, you will have gem version conflicts which will break your installation!
  
To install Redis, run the following:
+
The Ruby port will pull in several dependencies, including Python, which is why you must set a default version for it.
  
        sudo pkg_add -r redis
+
=== '''IMPORTANT TEMPORARY WORKAROUND''' ===
 +
Your Ruby build '''will fail''' out of the box currently (April 2014) on all versions! You must edit <code>lang/ruby21/Makefile</code> and change:
 +
<pre>--enable-dtrace</pre>
 +
to
 +
<pre>--disable-dtrace</pre>
  
And add `redis_enable="YES"` to /etc/rc.conf
+
=== Options: lang/python27 ===
 +
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.
  
== Ruby ==
+
== Ruby Gems Bundler ==
 +
You should not use Ruby to install Bundler unless you are installing it locally. Instead, you should use <code>sysutils/rubygem-bundler</code> 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 <code>sysutils/rubygem-bundler</code>.
  
=== To install Ruby (1.9): ===
+
== Node.js ==
 +
Node.js does not jump out at most people because of the way it is set up in ports. You are looking for <code>www/node</code>.
  
Add `RUBY_DEFAULT_VER=1.9` to /etc/make.conf and then run:
+
If you require Node Package Manager, you should install <code>www/npm</code> - however, this is optional as Diaspora* does not require NPM.
  
        cd /usr/ports/lang/ruby19 && sudo make install clean
+
= 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:
=== To install RubyGems, run the following: ===
 
  
        cd /usr/ports/devel/ruby-gems/ && sudo make install clean
+
== csh (FreeBSD default) ==
   
+
.cshrc
=== Recompile everything to synchronize dependencies and add required ports ===
+
<pre>
 +
setenv RAILS_ENV production
 +
setenv DB postgres
 +
</pre>
  
This is step is optional and very time-consuming:
+
== bash (optional package) ==
 +
.bashrc
 +
<pre>
 +
export RAILS_ENV='production'
 +
export DB='postgres'
 +
</pre>
  
        sudo portmaster -a
+
== ksh93 (optional package) ==
   
+
.kshrc
== Bundler ==
+
<pre>
 +
RAILS_ENV=production
 +
DB=postgres
 +
export RAILS_ENV DB
 +
</pre>
  
To install Bundler, run the following:
+
= 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!
  
        sudo gem install bundler
+
Instead, you should install your Gems under your Diaspora* user's installation to prevent any problems and ensure you have the correct versions.
 +
<pre>
 +
root@myhost # su - diaspora
 +
diaspora@myhost $ cd ~/diasporaInstallDir/
 +
diaspora@myhost ~/diasporaInstallDir/ $ bundle install --without test development --path vendor/bundle
 +
</pre>
 +
The <code>--path vendor/bundle</code> will install your Gems to diasporaInstallDir/vendor/bundle.
  
 
'''Congrats! You have all your dependencies installed'''. Go back to [[Installation/Backport#Get_the_source|Notes On Installing and Running Diaspora]].
 
'''Congrats! You have all your dependencies installed'''. Go back to [[Installation/Backport#Get_the_source|Notes On Installing and Running Diaspora]].

Revision as of 21:11, 4 April 2014

»» Work in progress
This article is a work in progress, it may contain incomplete or inaccurate information. There may be additional information on the talk page.
»» Note
This guide still needs to be rewritten for the the installation guides form


Caveat

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.

Versions

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.

Package Management

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 ports-mgmt/portmaster.

Prerequisites

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.

make.conf

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:

  • ports-mgmt/portmaster
  • security/ca_root_nss
  • devel/git

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.

The following packages are optional but recommended before you begin building Diaspora* on FreeBSD:

  • shells/bash
  • security/sudo

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.

  • databases/postgresql93-server
  • graphics/ImageMagick-nox11
  • databases/sqlite3
  • databases/redis
  • lang/ruby21 OR lang/ruby20 matching what you set in make.conf!
  • sysutils/rubygem-bundler
  • www/node

PostgreSQL

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:

  • databases/postgresql93-server

Optionally, you may also want to install:

  • databases/postgresql93-contrib

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.

Options: databases/postgresql93-server

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.

ImageMagick

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*.

Options: graphics/ImageMagick-nox11

It is recommended that you set only these options:

  • 16BIT_PIXEL
  • BZIP2
  • FONTCONFIG
  • FREETYPE
  • JPEG
  • LQR
  • LZMA
  • MODULES
  • PERL
  • PNG
  • THREADS
  • TIFF

This will minimize the number of dependencies which are pulled in. Do not select both JASPER and 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:

  • DOCS
  • FFTW
  • GRAPHVIZ
  • HDRI
  • OPENEXR

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.

Options: print/ghostscript9-nox11

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:

  • FONTCONFIG
  • ICONV
  • GS_jpeg, GS_jpeggray
  • GS_bit, GS_bitrgb, GS_bitcmyk
  • GS_plan
  • 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.

SQLite3

You should always use databases/sqlite3 rather than relying on any built-ins. SQLite3 is true to its name and pulls in essentially no dependencies.

You should generally use the default options. On busy pods or systems with lots of memory, you may wish to select TS2 - Memory by default - over the default of TS1. However you should only do this if you really know what you're doing!

Redis

When building 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.

Ruby

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 /etc/make.conf.

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 several dependencies, including Python, which is why you must set a default version for it.

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:

--enable-dtrace

to

--disable-dtrace

Options: lang/python27

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.

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 sysutils/rubygem-bundler.

Node.js

Node.js does not jump out at most people because of the way it is set up in ports. You are looking for www/node.

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)

.cshrc

setenv RAILS_ENV production
setenv DB postgres

bash (optional package)

.bashrc

export RAILS_ENV='production'
export DB='postgres'

ksh93 (optional package)

.kshrc

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

The --path vendor/bundle will install your Gems to diasporaInstallDir/vendor/bundle.

Congrats! You have all your dependencies installed. Go back to Notes On Installing and Running Diaspora.