Sugioarto

2016-05-01

Installing Phabricator in a FreeBSD Jail

I have written about Phabricator already and how useful it is for software development. In this post, I want to help with the installation of this project management tool.

These setup instructions apply to a typical setup that is done in FreeBSD jails. And I would not recommend to install it on a bare host, because it takes control of a full MariaDB installation that you might also want for other purposes, but you can't.

You need to make some preparations to install Phabricator. You will need an IP address and a host name for the web server.

Install Tools

cd /usr/ports/ports-mgmt/portmaster make install clean rehash portmaster -d sysutils/tmux portmaster -d devel/git

Set up mail server

This is optional, but Phabricator needs to send emails, a lot of them...

You can set up the jail to forward system emails to your main host. This is simply done by setting up sendmail:

cd /etc/mail make all

Now edit your-hostname.domain.tld.mc, insert a line like, where YOUR-JAIL-HOST-IP is the IP where you want to forward your emails to. Of course this host needs to run an MTA.

define(`SMART_HOST', `[YOUR-JAIL-HOST-IP]')

Install MariaDB

portmaster -d databases/mariadb100-server

Setup

You will need to insert this line into your /etc/rc.conf mysql_enable="YES"

Then start MariaDB with: /usr/local/etc/rc.d/mysql-server start

Secure your database with the following procedure:

mysql_secure_installation

Choose a secure password for root access and follow the standard procedure otherwise.

In case you have removed remote access, you can use this command in mysql client to allow connections:

mysql -u root -p mariadb-prompt# grant all privileges on *.* to root@'192.168.1.5' identified by 'YOUR-MARIADB-ROOT-PASSWORD' with grant option;

Install Phabricator

Do not install Phabricator from the ports collection!

Instead install the software directly from Github. Note that this is the only recommended and supported way to install Phabricator.

mkdir -p /usr/local/lib/php cd /usr/local/lib/php git clone https://github.com/phacility/libphutil.git git clone https://github.com/phacility/phabricator.git git clone https://github.com/phacility/arcanist.git

Usually, you would not like to run HEAD on a production server, so it's better to checkout the stable branch in the repositories.

cd /usr/local/lib/php/libphutil git checkout stable cd ../phabricator git checkout stable cd ../arcanist git checkout stable

PHP

Phabricator needs PHP and some additional modules. Install them. Note that the current recommended PHP version may change after some time. Here, PHP 5.6 is used.

portmaster -d lang/php56 textproc/php56-ctype ftp/php56-curl textproc/php56-dom sysutils/php56-fileinfo security/php56-filter graphics/php56-gd security/php56-hash converters/php56-iconv devel/php56-json converters/php56-mbstring databases/php56-mysql www/php56-opcache security/php56-openssl devel/php56-pcntl sysutils/php56-posix textproc/php56-simplexml textproc/php56-xml

Setup PHP-FPM

In /usr/local/etc/php-fpm.conf update these settings:

listen = /tmp/fcgiwrap.socket listen.owner = www listen.group = www listen.mode = 0660

You will need to insert this line into your /etc/rc.conf php_fpm_enable="YES"

Then start nginx with: /usr/local/etc/rc.d/php-fpm start

Install nginx

portmaster -d www/nginx

Setup

Take a look at the Phabricator setup for nginx in the docs.

The web root directory on FreeBSD is /usr/local/lib/php/phabricator/webroot. This is to be setup for the parameter root.

The /usr/local/etc/nginx/nginx.conf basically boils down to: http { ... client_max_body_size 64M; ... server { ... location / { root /usr/local/lib/php/phabricator/webroot; index index.php; rewrite ^/(.*)$ /index.php?__path__=/$1 last; } ... location /index.php { root /usr/local/lib/php/phabricator/webroot; fastcgi_pass unix:/tmp/fcgiwrap.socket; include /usr/local/etc/nginx/fastcgi_params; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } ... }

You will need to insert this line into your /etc/rc.conf nginx_enable="YES"

Then start nginx with: /usr/local/etc/rc.d/nginx start

Use the Phabricator Guide

The rest of the setup process is done best with the Phabricator application itself. Start up your web browser and enter the web URL that you have set up.

Configure Database Settings

Phabricator will ask you to configure MariaDB access:

/usr/local/lib/php/phabricator/bin/config set mysql.host YOUR-JAIL-IP /usr/local/lib/php/phabricator/bin/config set mysql.pass YOUR-MARIADB-ROOT-PASSWORD

Then also to execute storage upgrade:

/usr/local/lib/php/phabricator/bin/storage upgrade

You should also fix eventual issues, when storage upgrade suggests it.

Administrative Access

The guide will tell you to setup administrator access at this point. You don't need to separate the admin from users, if you are a user yourself. Just setup your account here in this case.

Unresolved Issues

Visiting the Phabricator installation again (keep on refreshing the browser tab), will tell you about problems with your installation. Resolve them one after another until Phabricator is satisfied.

Here are solutions to some "issues" that occur on FreeBSD installations.

Base URI

/usr/local/lib/php/phabricator/bin/config set phabricator.base-uri 'http://YOUR-JAIL-HOSTNAME/'

PHP setup

cd /usr/local/etc/ cp php.ini-production php.ini

In /usr/local/etc/php.ini, replace the post_max_size setting to this value:

post_max_size = 64M

and insert these lines:

date.timezone = Europe/Berlin opcache.validate_timestamps=0

Then restart PHP-FPM:

/usr/local/etc/rc.d/php-fpm restart

Authentication Setup

Follow the guide to set up Authentication Providers directly in the web UI.

Enable Pygments

Follow the guide to set up Pygments. It is also done with the web UI.

Alternate File Domain

You can ignore this issue, but read about the implications, because it is important in cases you offer public access over internet.

Fixing MariaDB performance issues

In /var/db/mysql/my.cnf:

[mysqld] max_allowed_packet=128M sql_mode=STRICT_ALL_TABLES ft_stopword_file=/usr/local/lib/php/phabricator/resources/sql/stopwords.txt ft_min_word_len=3 ft_boolean_syntax=' |-><()~*:""&^' innodb_buffer_pool_size=1000M

Then restart the MariaDB server and repair the search table.

/usr/local/etc/rc.d/mysql-server restart mysql -u root -p mysql-prompt# REPAIR TABLE phabricator_search.search_documentfield;

Setup storage

For local file storage:

mkdir -p /usr/local/www/phab/files chown -R phd:www /usr/local/www/phab/files chmod -R 775 /usr/local/www/phab/files /usr/local/lib/php/phabricator/bin/config set storage.local-disk.path /usr/local/www/phab/files

phd Daemon

Make phd user and add to group www. Simply answer what adduser asks and set Phabricator phd user to phd.

adduser /usr/local/lib/php/phabricator/bin/config set phd.user phd /usr/local/etc/rc.d/phd stop chown -R phd:phd /var/tmp/phd /usr/local/etc/rc.d/phd start

Insert into /etc/rc.conf:

phd_enable="YES"

Diffusion setup

Add user git for your VCS user and set home directory to /usr/local/www/phab/git.

adduser

Install sudo and make the repository root:

portmaster -d security/sudo mkdir /usr/local/www/phab/repo chown -R phd:phd /usr/local/www/phab/repo /usr/local/lib/php/phabricator/bin/config set repository.default-local-path /usr/local/www/phab/repo /usr/local/lib/php/phabricator/bin/config set diffusion.ssh-user git

Use visudo to insert this line into the configuration:

git ALL=(phd) SETENV: NOPASSWD: /usr/local/bin/git-upload-pack, /usr/local/bin/git-receive-pack

Setup SSH Access

First move the existing sshd to port 222 by setting this line in /etc/ssh/sshd_config

Port 222

Restart the jail on the jail host with and reconnect, this time (and from now on!) using port 222. Continue with user root:

/etc/rc.d/jail restart phab ssh -p222 user@YOUR-JAIL-HOST-IP su -l cp /usr/local/lib/php/phabricator/resources/sshd/sshd_config.phabricator.example /etc/ssh/sshd_config.phabricator

Copy this to /etc/ssh/sshd_config.phabricator

AuthorizedKeysCommand /etc/ssh/phabricator-ssh-hook.sh AuthorizedKeysCommandUser git AllowUsers git Port 22 Protocol 2 PermitRootLogin no AllowAgentForwarding no AllowTcpForwarding no PrintMotd no PrintLastLog no PasswordAuthentication no AuthorizedKeysFile none PidFile /var/run/sshd-phabricator.pid

Then copy the ssh hook script that is a part of the Phabricator distribution:

cp /usr/local/lib/php/phabricator/resources/sshd/phabricator-ssh-hook.sh /etc/ssh/phabricator-ssh-hook.sh

Take a look at /etc/ssh/phabricator-ssh-hook.sh and correct 2 lines and add a small path correction:

VCSUSER="git" ... PATH=$PATH:/usr/local/bin ROOT="/usr/local/lib/php/phabricator"

Then start the sshd manually: /usr/sbin/sshd -f /etc/ssh/sshd_config.phabricator

Upload an ssh key to your user's profile in Phabricator. It behind the Tool button (in top right corner), then click in sidebar menu on SSH Public Keys.

Now test the access using this public key by typing:

echo {} | ssh git@YOUR-JAIL-IP conduit conduit.ping

After confirming with yes (you won't see it again), it should return something like this:

{"result":"JAIL-HOST-NAME","error_code":null,"error_info":null}

If not, something is wrong. Take a look here for more information.

Some improvements

The startup method of Phabricator services is not very well suited for FreeBSD jails. It is better to add some startup scripts that also fix a few problems.

I have published the scripts needed to startup the typical services here:

In rc.conf add these lines:

phabricator_sshd_enable="YES" phabricator_phd_enable="YES" phabricator_aphlict_enable="YES"

Handle upgrades

Read this article.