This is very much a work in progress. Do not follow these instructions on a production system. Help, edits, etc. cheerfully accepted. Discussion thread here.

Installing and integrating Phabricator on a Nethserver 7.5 system. This is a pretty complicated installation, as there are several moving pieces which need to fit together. Almost all the work will be done at the command line as the root user.

This how-to will create a Virtual Host on your Nethserver box for phab.yourdomain. Do not create a virtual host with this name through the server manager, and also do not name your server phab.yourdomain–either will conflict with this how-to.

This how-to also installs git, Subversion, and Mercurial. Git must be installed in any event, as it's needed to install the components of Phabricator. Subversion and Mercurial are not required. They are included because Phabricator supports repositories of all three types. If you prefer, they may be omitted.

Installation

These instructions begin with a fresh installation of Nethserver 7.5, with all updates installed. From software center, install mysql and web server (with all options except php-mysql; you'll install a different PHP mysql client below). Following the instructions here, install nethserver-php-scl. Then, at the CLI, run:

yum install -y php-mysqlnd python-pygments git nano subversion mercurial php72-php-apcu php72-php-opcache
config setprop php72 PostMaxSize 32
signal-event nethserver-php-scl-update
useradd phd
useradd vcs
usermod -p NP vcs
mkdir -p /var/tmp/phd
cd /var/lib/nethserver/vhost
mkdir phab
cd phab
git clone https://github.com/phacility/libphutil.git
git clone https://github.com/phacility/arcanist.git
git clone https://github.com/phacility/phabricator.git
chown -R apache:apache .
cd phabricator
bin/config set mysql.pass $(cat /var/lib/nethserver/secrets/mysql)
bin/storage upgrade --force
mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf.d/virtualhosts.conf/
cd /etc/e-smith/templates-custom/etc/httpd/conf.d/virtualhosts.conf/
nano 15_phabricator

You're creating a Virtual Host template Fragment; its contents should be as below:

{
$OUT .= <<EOF
<VirtualHost *:80>
  DocumentRoot "/var/lib/nethserver/vhost/phab/phabricator/webroot"
  ServerName phab.$DomainName
  RewriteEngine on
  RewriteRule ^/\\.well-known/ - [L]
  RewriteRule (.*) https://phab.$DomainName\$1 [R,L]
  Alias "/.well-known/acme-challenge/" "/var/www/html/.well-known/acme-challenge/"
  <Directory "/var/www/html/.well-known/acme-challenge/">
     Require all granted
     Options -Indexes -FollowSymLinks
     AllowOverride None
  </Directory>
</VirtualHost>

<VirtualHost *:443>
  DocumentRoot "/var/lib/nethserver/vhost/phab/phabricator/webroot"
  ServerName phab.$DomainName
  RewriteEngine on
  RewriteCond %{HTTP:Authorization} ^(.*)
  RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
  RewriteRule ^(.*)\$          /index.php?__path__=\$1  [B,L,QSA]
  SSLEngine on
  <FilesMatch .php\$>
    SetHandler "proxy:fcgi://127.0.0.1:9072"
  </FilesMatch>
  <Directory "/var/lib/nethserver/vhost/phab/phabricator/webroot">
    Require all granted
  </Directory>
</VirtualHost>
EOF
}

Then run

expand-template /etc/httpd/conf.d/virtualhosts.conf 
systemctl reload httpd

At this point, the most basic installation is finished. You can at this point, if you choose, browse to http://phab.yourdomain, set up an admin user/password, and begin to configure your installation. But you'll see a number of setup warnings, most of which will be addressed in the next section.

Fix Setup Warnings

The steps above will produce an installation with many warnings; the steps below should address most of them. First, create a directory for your repositories:

mkdir /var/repo
chown apache:phd /var/repo
chmod 775 /var/repo
/var/lib/nethserver/vhost/phab/phabricator/bin/config set storage.local-disk.path /var/repo

Set the Opcache configuration correctly. nano /etc/opt/remi/php72/php.d/10-opcache.ini. Find the line that says:

;opcache.validate_timestamps=1

…and change it to

opcache.validate_timestamps=0

Set the MySQL MaxAllowedPacket appropriately:

config setprop mysqld MaxAllowedPacket 32M
signal-event nethserver-mysql-save

Set the base URL for your installation:

/var/lib/nethserver/vhost/phab/phabricator/bin/config set phabricator.base-uri "https://phab.$(config get DomainName)/"

Create /etc/php.d/phabricator.ini with following content:

always_populate_raw_post_data = "-1"

Create /etc/my.cnf.d/phabricator.cnf:

[mysqld]
sql_mode=STRICT_ALL_TABLES
innodb_buffer_pool_size=1600M

Restart httpd and mysqld:

systemctl restart httpd mysqld

Now we'll configure the Phabricator daemons to run as the correct user, and to start automatically when your system restarts:

chown -R phd:phd /var/tmp/phd
/var/lib/nethserver/vhost/phab/phabricator/bin/phd stop
/var/lib/nethserver/vhost/phab/phabricator/bin/config set phd.user phd
nano /etc/systemd/system/phd.service

The contents of that file should be as below:

[Unit]
Description=Phabricator Daemons
After=network.target,mysql.service
Requires=network.target,mysql.service

[Service]
Type=forking
User=phd
ExecStart=/var/lib/nethserver/vhost/phab/phabricator/bin/phd start
ExecStop=/var/lib/nethserver/vhost/phab/phabricator/bin/phd stop
Restart=always
RestartSec=10
StartLimitInterval=0
StartLimitBurst=0

[Install]
WantedBy=multi-user.target

Save that file, then start the daemons:

systemctl enable phd --now

Finally, we'll enable pygments for code highlighting:

/var/lib/nethserver/vhost/phab/phabricator/bin/config set pygments.enabled true

If you now log in as the admin user, you'll see one remaining setup issue, the alternate file domain. This will not be addressed here.

Users/Permissions for code checkout and update

In order for users to be able to check out code and commit changes, there's quite a bit of configuration that needs to be done. The relevant users were created above, but the system needs to be set up to allow them to perform the relevant updates. These instructions will set up your system to support these operations via HTTP (if supported by your version control system of choice) and SSH. As part of the process, this will create a second sshd service running on port 2222. If your main SSH service is running on port 2222, you'll need to choose a different port below. From the CLI, run:

/var/lib/nethserver/vhost/phab/phabricator/bin/config set diffusion.ssh-user vcs
nano /etc/sudoers.d/50_phabricator

The contents of this file should be:

apache ALL=(phd) SETENV: NOPASSWD: /usr/bin/git, /usr/bin/hg, /usr/bin/ssh, /usr/libexec/git-core/git-http-backend
vcs ALL=(phd) SETENV: NOPASSWD: /usr/bin/git, /usr/bin/git-upload-pack, /usr/bin/git-receive-pack, /usr/bin/hg, /usr/bin/ssh, /usr/bin/svnserve

Note that this file should consist of only two lines–one line starting with “apache”, and one line starting with “vcs”. Save the file and continue. Then:

cd /var/lib/nethserver/vhost/phab/phabricator
nano path.json

Its contents should be

[
    "/usr/local/sbin",
    "/usr/local/bin",
    "/usr/sbin",
    "/usr/bin",
    "/usr/libexec/git-core"
]

Save the file and exit. Then import it into your configuration and set the SSH port:

bin/config set environment.append-paths --stdin < path.json
bin/config set diffusion.ssh-port 2222

You'll need to create a SSH hook script:

nano /usr/libexec/phabricator-ssh-hook.sh

Its contents should be:

#!/bin/sh

# NOTE: Replace this with the username that you expect users to connect with.
VCSUSER="vcs"

# NOTE: Replace this with the path to your Phabricator directory.
ROOT="/var/lib/nethserver/vhost/phab/phabricator/"

if [ "$1" != "$VCSUSER" ];
then
  exit 1
fi

exec "$ROOT/bin/ssh-auth" $@

Save the file and continue. Then:

chown root /usr/libexec
chown root /usr/libexec/phabricator-ssh-hook.sh 
chmod 755 /usr/libexec/phabricator-ssh-hook.sh

Because we're creating a new network service on port 2222, we need to set the firewall appropriately:

config set fw_sshd-phabricator service status enabled TCPPort 2222 access red,green
signal-event firewall-adjust

Now we need to create a configuration file for the new sshd service:

nano /etc/ssh/sshd_config.phabricator

Its contents should look like this:

# NOTE: You must have OpenSSHD 6.2 or newer; support for AuthorizedKeysCommand
# was added in this version.

# NOTE: Edit these to the correct values for your setup.

AuthorizedKeysCommand /usr/libexec/phabricator-ssh-hook.sh
AuthorizedKeysCommandUser vcs
AllowUsers vcs

# You may need to tweak these options, but mostly they just turn off everything
# dangerous.

Port 2222
HostKey /etc/ssh/ssh_host_ecdsa_key
HostKey /etc/ssh/ssh_host_ed25519_key
HostKey /etc/ssh/ssh_host_rsa_key
Protocol 2
PermitRootLogin no
AllowAgentForwarding no
AllowTcpForwarding no
PrintMotd no
PrintLastLog no
PasswordAuthentication no
ChallengeResponseAuthentication no
AuthorizedKeysFile none

PidFile /var/run/sshd-phabricator.pid

Save the file and exit. Then, a systemd unit file for the new service:

nano /etc/systemd/system/sshd-phabricator.service

Its contents should be:

[Unit]
Description=OpenSSH server daemon - Phabricator Installation
Documentation=man:sshd(8) man:sshd_config(5)
After=network.target sshd-keygen.service
Wants=sshd-keygen.service

[Service]
Type=notify
EnvironmentFile=/etc/sysconfig/sshd
ExecStart=/usr/sbin/sshd -f /etc/ssh/sshd_config.phabricator -D $OPTIONS
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
RestartSec=42s

[Install]
WantedBy=multi-user.target

Save the file and exit. Then start the service:

systemctl enable sshd-phabricator --now

Email Configuration

Most email configuration must be done at the command line. Phabricator supports multiple email systems; the simplest to configure would be either the local sendmail binary or some other specified SMTP server. Start by creating a mailers.json file: nano mailers.json. If you want to use the local sendmail binary, it should look like this:

[
  {
    "key": "mailer",
    "type": "sendmail"
  }
]

For a different SMTP server, it should look like this instead:

[
  {
    "key": "mailer",
    "type": "smtp",
    "host": "mailservername",
    "port": "port #",
    "username": "user_name",
    "password": "user_password",
    "protocol": "ssl/tls"
  }
]

Port, username, password, and protocol are all optional. For more information about configuring other mail services, see the Phabricator documentation.

Once the file is created, run bin/config set cluster.mailers –stdin < mailers.json

Authentication

Phabricator supports authentication through many mechanisms. This document will address username/password and LDAP authentication. Either will be configured using the Auth app. Log into your Phabricator instance, and from the left gutter, click on the Auth app. Then click the “Add Provider” button.

Username/password

The Username/password validator will set up Phabricator with its own database of usernames and passwords, which will be independent of your Nethserver's users. To use this, after clicking the Add Provider button, select the Username/password provider.

LDAP

LDAP authentication will let your Phabricator installation authenticate using your Nethserver's users. After clicking the Add Provider button, select the LDAP provider and click Continue. Then enter the following settings:

LDAP Hostname: ldap://127.0.0.1

            or ldaps://sub.domain.tld

LDAP Port: 389 or 636

Base Distinguished Name: ou=People,dc=directory,dc=nh

Search Attributes: uid

Username Attribute: sn

Realname Attributes: cn

Upgrading Phabricator

It's recommended that you update Phabricator roughly weekly to the latest version in the GitHub repository. To do this, place the following script in /etc/cron.weekly/phab_upgrade.sh:

#!/bin/sh

set -e
set -x

ROOT="/var/lib/nethserver/vhost/phab" 

### UPDATE WORKING COPIES ######################################################

cd $ROOT/libphutil
git pull

cd $ROOT/arcanist
git pull

cd $ROOT/phabricator
git pull

### CYCLE WEB SERVER AND DAEMONS ###############################################

# Stop daemons.
systemctl stop phd

# Stop the webserver

systemctl stop httpd

# Upgrade the database schema. 
$ROOT/phabricator/bin/storage upgrade --force

# Restart the webserver. 
systemctl start httpd

# Restart daemons.
systemctl start phd

Make it executable by running chmod +x phab_upgrade.sh.

Known Issues

The virtual host configuration interferes with obtaining a TLS certificate from Let's Encrypt–it blocks access to the /.well-known/acme-challenge path. This can be avoided temporarily by installing letsencrypt ssl before beginning the installation process, but renewal will still fail. This can be completely avoided by using DNS validation to obtain your cert, but the Virtual Host configuration really needs to be fixed.

This should now be fixed with the updated Virtual Host configuration. Please test.