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 need to load the Phabricator
schemata into it. First, load the initial database schema.

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

After this you need to upgrade the schema (see @{article:Upgrading Schema}),
but you need to finish the rest of the configuration first.

= Configuring Phabricator =

Create a new file here:

  path/to/phabricator/conf/custom/myconfig.conf.php

...where ##myconfig## is some name which identifies your installation. Put this
in the file:

  <?php

  return array(

    // Important! This will put Phabricator into setup mode to help you
    // configure things.
    'phabricator.setup' => true,

  ) + phabricator_read_config_file('production');

For the last line, you can also use ##'development'## instead of
##'production'## if you are planning to develop Phabricator itself. This will
turn on some debugging features.

= 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 the config file you set up in the previous step. If you
    # called it something other than 'myconfig', put that here.
    SetEnv PHABRICATOR_ENV custom/myconfig
  </VirtualHost>

Now, restart apache and navigate to whichever subdomain you set up. You should
either see the Phabricator setup screen, which is a simple text page that looks
something like this:

  PHABRICATOR SETUP

  This setup mode will guide you through setting up your Phabricator
  configuration.

  >>>  REQUIRED PHP EXTENSIONS  ------------------------------------------------
  ...

If you see this, you're in good shape. Follow the instructions and correct any
problems setup detects. If you don't see it but you do see a useful error
message, try to fix that. If neither of these cover you, something is wrong.
If you can't figure it out, come get help in IRC or on the mailing list (see
http://phabricator.org/ for links).

= Configuring Phabricator =

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

  /path/to/phabricator/conf/default.conf.php

There are several builtin configurations:

  - ##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.

To actually configure your install, edit your ##custom/myconfig.conf.php## file
and override values from either the ##'production'## or ##'development'##
configurations. You should not edit the builtin configurations directly because
that will make upgrading Phabricator more difficult in the future.

= Upgrading Schema =

After you have configured Phabricator, you need to upgrade the database
schema -- see @{article:Upgrading Schema}. You'll also need to do this after you
update the code in the future.