phorge-phorge/src/docs/configuration_guide.diviner

@title Configuration Guide
@group config

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 @{article:Installation Guide}.

= Configuring MySQL =

Get MySQL running and verify you can connect to it. Consult the MySQL
documentation for help. When MySQL works, you just need to load the Phabricator
schemata into it:

  mysql -uroot < path/to/phabricator/resources/sql/init/initialize.sql

= Configuring Apache =

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.

Now, either create a VirtualHost entry (to put Phabricator on a subdomain)
or edit the Directory entry for the DocumentRoot. It should look something like
this:

  <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.
    DocumentRoot /path/to/phabricator/webroot
    
    RewriteEngine on
    RewriteRule ^/rsrc/(.*)     -                       [L,QSA]
    RewriteRule ^/favicon.ico   -                       [L,QSA]
    RewriteRule ^(.*)$          /index.php?__path__=$1  [L,QSA]

    # This will use "setup" defaults for configuration options, which will
    # expose error messages. Before you make the install public, you should
    # change this to "production" and/or customize your configuration. See
    # the next section for details.
    SetEnv PHABRICATOR_ENV setup
  </VirtualHost>
  
Now, restart apache and navigate to whichever subdomain you set up. You should
either see the Phabricator login screen, which means you're all set, or some
useful error message telling you what else you need to fix (for instance, you
may need to set up MySQL credentials). If you see something else, you did
something very wrong and/or this document lied to you.


= Configuring Phabricator =

Now that basic setup is complete, you should configure Phabricator. Phabricator
configuration options which control how the applications behave are stored here:

  /path/to/phabricator/conf/
  
There are several configuration templates:

  - default.conf.php: root configuration, lists every configuration option and
    sets some default for it. Look in this file to figure out what you can
    configure.
  - development.conf.php: pulls in default.conf.php, but overrides some
    configuration options to better values for doing development on Phabricator.
    You probably don't need to even look at this file unless you're making
    changes to Phabricator itself.
  - production.conf.php: pulls in default.conf.php, but overrides some
    configuration options to provide better values for a production install.
    Once you've completed setup, you should switch to this configuration or
    one based upon it.
  - setup.conf.php: pulls in default.conf.php, but sets some flags that make
    it easier to set up a Phabricator install. Switch away from this before
    deploying a production install.
  
While you can use these templates as-is, you'll probably want to set up custom
configuration. To do this, create a new file:

  /path/to/phabricator/conf/custom/myconfig.conf.php
  
Put this in the file:

  <?php

  return array(
  
    // This is just an example.
    'some.config' => 'some_value',

  ) + phabricator_read_config_file('production');

This will create a new config called "custom/myconfig" which uses the
"production" config as the default but allows you to override options. You can
select it by editing the VirtualHost or Directory entry you set up when
configuring Apache:

  <VirtualHost *>
    # ...
    SetEnv PHABRICATOR_ENV custom/myconfig
    # ...
  </VirtualHost>
  
Now, look through ##default.conf.php## and override any options you want to
change by providing overrides in ##myconfig.conf.php##.