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.

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. you might also be required to run this, to enable latest evrsion of php https://wiki.nethserver.org/doku.php?id=php-scl#use_the_php_cli 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
source scl_source enable php72
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.

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
<del>/var/lib/nethserver/vhost/phab/phabricator/bin/config set storage.local-disk.path /var/repo</del>
/bin/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/bin; php -dmemory_limit=512M 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=/bin/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/phab/phabricator/bin; php -dmemory_limit=512M phd start"
ExecStop=/bin/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/phab/phabricator/bin; php -dmemory_limit=512M 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/dev/phabricator/bin; config set pygments.enabled true
/bin/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/bin; php -dmemory_limit=512M 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.

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/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/bin; php -dmemory_limit=512M config set environment.append-paths --stdin < ~/path.json"
/bin/bash -c "source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/bin; php -dmemory_limit=512M 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

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/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/bin; php -dmemory_limit=512M config set cluster.mailers –stdin < ~/mailers.json”

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.

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 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: <code> #!/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 </code> “cd /etc/cron.weekly” Make it executable by running chmod +x phab_upgrade.sh. ==== SETTING UP S3 STORAGE ==== This is going to show you how to implement amazon s3 as the storage for files and images. To enable file storage in S3, set these keys: amazon-s3.access-key: Your AWS access key. amazon-s3.secret-key: Your AWS secret key. amazon-s3.region: Your AWS S3 region. amazon-s3.endpoint: Your AWS S3 endpoint. storage.s3.bucket: S3 bucket name where files should be stored. <file> /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/config set amazon-s3.region nl-ams” /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/config set amazon-s3.endpoint s3.nl-ams.scw.cloud” /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/config set amazon-s3.access-key the TheAccessKeyContent” /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/config set amazon-s3.secret-key TheSecretKeyContent” /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/config set storage.s3.bucket BucketName” </file> After adding the configurations, Try copying any file to the homepage to test, if file is uploaded, all is well. test copying one file to the new engine using <file> ./bin/files migrate –engine amazon-s3 F36 </file> <file> /bin/bash -c “source /opt/rh/rh-php72/enable; cd /var/lib/nethserver/vhost/dev/phabricator/; php -dmemory_limit=512M ./bin/files migrate –engine amazon-s3 –all” </file> If that works use <file> ./bin/files migrate –engine amazon-s3 –all </file> to copy all files ==== 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.