Page MenuHomeClusterLabs Projects
Diviner Phabricator User Docs Configuration Guide

Configuration Guide
Phabricator User Documentation (Configuration)

This document contains basic configuration instructions for Phabricator.

Prerequisites

This document assumes you've already installed all the components you need. If you haven't, see Installation Guide.

The next steps are:

  • Configure your webserver (Apache, nginx, or lighttpd).
  • Access Phabricator with your browser.
  • Follow the instructions to complete setup.

Webserver: Configuring Apache

NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll down to their sections.

Get Apache running and verify it's serving a test page. Consult the Apache documentation for help. Make sure mod_php and mod_rewrite are enabled, and mod_ssl if you intend to set up SSL.

If you haven't already, set up a domain name to point to the host you're installing on. You can either install Phabricator on a subdomain (like phabricator.example.com) or an entire domain, but you can not install it in some subdirectory of an existing website. Navigate to whatever domain you're going to use and make sure Apache serves you something to verify that DNS is correctly configured.

NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like 'http://example/'. Some web browsers will not set cookies otherwise.

Now create a VirtualHost entry for Phabricator. It should look something like this:

httpd.conf
<VirtualHost *>
  # Change this to the domain which points to your host.
  ServerName phabricator.example.com

  # Change this to the path where you put 'phabricator' when you checked it
  # out from GitHub when following the Installation Guide.
  #
  # Make sure you include "/webroot" at the end!
  DocumentRoot /path/to/phabricator/webroot

  RewriteEngine on
  RewriteRule ^(.*)$          /index.php?__path__=$1  [B,L,QSA]
</VirtualHost>

If Apache isn't currently configured to serve documents out of the directory where you put Phabricator, you may also need to add <Directory /> section. The syntax for this section depends on which version of Apache you're running. (If you don't know, you can usually figure this out by running httpd -v.) For Apache versions older than 2.4, use this:

Apache Older Than 2.4
<Directory "/path/to/phabricator/webroot">
  Order allow,deny
  Allow from all
</Directory>

For Apache versions 2.4 and newer, use this:

Apache 2.4 and Newer
<Directory "/path/to/phabricator/webroot">
  Require all granted
</Directory>

After making your edits, restart Apache, then continue to "Setup" below.

Webserver: Configuring nginx

NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll to their sections.

For nginx, use a configuration like this:

nginx.conf
server {
  server_name phabricator.example.com;
  root        /path/to/phabricator/webroot;

  location / {
    index index.php;
    rewrite ^/(.*)$ /index.php?__path__=/$1 last;
  }

  location /index.php {
    fastcgi_pass   localhost:9000;
    fastcgi_index   index.php;

    #required if PHP was built with --enable-force-cgi-redirect
    fastcgi_param  REDIRECT_STATUS    200;

    #variables to make the $_SERVER populate in PHP
    fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
    fastcgi_param  QUERY_STRING       $query_string;
    fastcgi_param  REQUEST_METHOD     $request_method;
    fastcgi_param  CONTENT_TYPE       $content_type;
    fastcgi_param  CONTENT_LENGTH     $content_length;

    fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;

    fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
    fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;

    fastcgi_param  REMOTE_ADDR        $remote_addr;
  }
}

Restart nginx after making your edits, then continue to "Setup" below.

Webserver: Configuring lighttpd

NOTE: Follow these instructions to use lighttpd. To use Apache or nginx, scroll up to their sections.

For lighttpd, add a section like this to your lighttpd.conf:

$HTTP["host"] =~ "phabricator(\.example\.com)?" {
    server.document-root = "/path/to/phabricator/webroot"
    url.rewrite-once = (
        # This simulates QSA ("query string append") mode in apache
        "^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
        "^(/.*)$" => "/index.php?__path__=$1",
    )
}

You should also ensure the following modules are listed in your server.modules list:

mod_fastcgi
mod_rewrite

Finally, you should run the following commands to enable php support:

$ sudo apt-get install php5-cgi  # for Ubuntu; other distros should be similar
$ sudo lighty-enable-mod fastcgi-php

Restart lighttpd after making your edits, then continue below.

Load Balancer Health Checks

If you're using a load balancer in front of your webserver, you can configure it to perform health checks using the path /status/.

Setup

Now, navigate to whichever subdomain you set up. You should see instructions to continue setup. The rest of this document contains additional instructions for specific setup steps.

When you resolve any issues and see the welcome screen, enter credentials to create your initial administrator account. After you log in, you'll want to configure how other users will be able to log in or register -- until you do, no one else will be able to sign up or log in. For more information, see Configuring Accounts and Registration.

Storage: Configuring MySQL

During setup, you'll need to configure MySQL. To do this, get MySQL running and verify you can connect to it. Consult the MySQL documentation for help. When MySQL works, you need to load the Phabricator schemata into it. To do this, run:

phabricator/ $ ./bin/storage upgrade

If your configuration uses an unprivileged user to connect to the database, you may have to override the default user so the schema changes can be applied with root or some other admin user:

phabricator/ $ ./bin/storage upgrade --user <user> --password <password>

You can avoid the prompt the script issues by passing the --force flag (for example, if you are scripting the upgrade process).

phabricator/ $ ./bin/storage upgrade --force
NOTE: When you update Phabricator, run storage upgrade again to apply any new updates.

Next Steps

Continue by:

Defined
src/docs/user/configuration/configuration_guide.diviner:1