[Summary view] [Print] [Text view]

   1  @title Configuration Guide
   2  @group config
   3  
   4  This document contains basic configuration instructions for Phabricator.
   5  
   6  = Prerequisites =
   7  
   8  This document assumes you've already installed all the components you need.
   9  If you haven't, see @{article:Installation Guide}.
  10  
  11  The next steps are:
  12  
  13    - Configure your webserver (Apache, nginx, or lighttpd).
  14    - Access Phabricator with your browser.
  15    - Follow the instructions to complete setup.
  16  
  17  = Webserver: Configuring Apache =
  18  
  19  NOTE: Follow these instructions to use Apache. To use nginx or lighttpd, scroll
  20  down to their sections.
  21  
  22  Get Apache running and verify it's serving a test page. Consult the Apache
  23  documentation for help. Make sure ##mod_php## and ##mod_rewrite## are enabled,
  24  and ##mod_ssl## if you intend to set up SSL.
  25  
  26  If you haven't already, set up a domain name to point to the host you're
  27  installing on. You can either install Phabricator on a subdomain (like
  28  phabricator.example.com) or an entire domain, but you can not install it in
  29  some subdirectory of an existing website. Navigate to whatever domain you're
  30  going to use and make sure Apache serves you something to verify that DNS
  31  is correctly configured.
  32  
  33  NOTE: The domain must contain a dot ('.'), i.e. not be just a bare name like
  34  'http://example/'. Some web browsers will not set cookies otherwise.
  35  
  36  Now create a VirtualHost entry for Phabricator. It should look something like
  37  this:
  38  
  39    name=httpd.conf
  40    <VirtualHost *>
  41      # Change this to the domain which points to your host.
  42      ServerName phabricator.example.com
  43  
  44      # Change this to the path where you put 'phabricator' when you checked it
  45      # out from GitHub when following the Installation Guide.
  46      #
  47      # Make sure you include "/webroot" at the end!
  48      DocumentRoot /path/to/phabricator/webroot
  49  
  50      RewriteEngine on
  51      RewriteRule ^/rsrc/(.*)     -                       [L,QSA]
  52      RewriteRule ^/favicon.ico   -                       [L,QSA]
  53      RewriteRule ^(.*)$          /index.php?__path__=$1  [B,L,QSA]
  54    </VirtualHost>
  55  
  56  If Apache isn't currently configured to serve documents out of the directory
  57  where you put Phabricator, you may also need to add `<Directory />` section. The
  58  syntax for this section depends on which version of Apache you're running.
  59  (If you don't know, you can usually figure this out by running `httpd -v`.)
  60  For Apache versions older than 2.4, use this:
  61  
  62    name="Apache Older Than 2.4"
  63    <Directory "/path/to/phabricator/webroot">
  64      Order allow,deny
  65      Allow from all
  66    </Directory>
  67  
  68  For Apache versions 2.4 and newer, use this:
  69  
  70    name="Apache 2.4 and Newer"
  71    <Directory "/path/to/phabricator/webroot">
  72      Require all granted
  73    </Directory>
  74  
  75  After making your edits, restart Apache, then continue to "Setup" below.
  76  
  77  = Webserver: Configuring nginx =
  78  
  79  NOTE: Follow these instructions to use nginx. To use Apache or lighttpd, scroll
  80  to their sections.
  81  
  82  For nginx, use a configuration like this:
  83  
  84    name=nginx.conf
  85    server {
  86      server_name phabricator.example.com;
  87      root        /path/to/phabricator/webroot;
  88  
  89      location / {
  90        index index.php;
  91        rewrite ^/(.*)$ /index.php?__path__=/$1 last;
  92      }
  93  
  94      location = /favicon.ico {
  95        try_files $uri =204;
  96      }
  97  
  98      location /index.php {
  99        fastcgi_pass   localhost:9000;
 100        fastcgi_index   index.php;
 101  
 102        #required if PHP was built with --enable-force-cgi-redirect
 103        fastcgi_param  REDIRECT_STATUS    200;
 104  
 105        #variables to make the $_SERVER populate in PHP
 106        fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
 107        fastcgi_param  QUERY_STRING       $query_string;
 108        fastcgi_param  REQUEST_METHOD     $request_method;
 109        fastcgi_param  CONTENT_TYPE       $content_type;
 110        fastcgi_param  CONTENT_LENGTH     $content_length;
 111  
 112        fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
 113  
 114        fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 115        fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
 116  
 117        fastcgi_param  REMOTE_ADDR        $remote_addr;
 118      }
 119    }
 120  
 121  Restart nginx after making your edits, then continue to "Setup" below.
 122  
 123  = Webserver: Configuring lighttpd =
 124  
 125  NOTE: Follow these instructions to use lighttpd. To use Apache or niginx, scroll
 126  up to their sections.
 127  
 128  For lighttpd, add a section like this to your lighttpd.conf:
 129  
 130    $HTTP["host"] =~ "phabricator(\.example\.com)?" {
 131        server.document-root = "/path/to/phabricator/webroot"
 132        url.rewrite-once = (
 133            "^(/rsrc/.*)$" => "$1",
 134            "^(/favicon.ico)$" => "$1",
 135            # This simulates QSA ("query string append") mode in apache
 136            "^(/[^?]*)\?(.*)" => "/index.php?__path__=$1&$2",
 137            "^(/.*)$" => "/index.php?__path__=$1",
 138        )
 139    }
 140  
 141  You should also ensure the following modules are listed in your
 142  server.modules list:
 143  
 144    mod_fastcgi
 145    mod_rewrite
 146  
 147  Finally, you should run the following commands to enable php support:
 148  
 149    $ sudo apt-get install php5-cgi  # for ubuntu; other distros should be similar
 150    $ sudo lighty-enable-mod fastcgi-php
 151  
 152  Restart lighttpd after making your edits, then continue below.
 153  
 154  = Setup =
 155  
 156  Now, navigate to whichever subdomain you set up. You should see instructions to
 157  continue setup. The rest of this document contains additional instructions for
 158  specific setup steps.
 159  
 160  When you resolve any issues and see the welcome screen, enter credentials to
 161  create your initial administrator account. After you log in, you'll want to
 162  configure how other users will be able to log in or register -- until you do,
 163  no one else will be able to sign up or log in. For more information, see
 164  @{article:Configuring Accounts and Registration}.
 165  
 166  = Storage: Configuring MySQL =
 167  
 168  During setup, you'll need to configure MySQL. To do this, get MySQL running and
 169  verify you can connect to it. Consult the MySQL documentation for help. When
 170  MySQL works, you need to load the Phabricator schemata into it. To do this, run:
 171  
 172    phabricator/ $ ./bin/storage upgrade
 173  
 174  If your configuration uses an unprivileged user to connect to the database, you
 175  may have to override the default user so the schema changes can be applied with
 176  root or some other admin user:
 177  
 178    phabricator/ $ ./bin/storage upgrade --user <user> --password <password>
 179  
 180  You can avoid the prompt the script issues by passing the ##--force## flag (for
 181  example, if you are scripting the upgrade process).
 182  
 183    phabricator/ $ ./bin/storage upgrade --force
 184  
 185  NOTE: When you update Phabricator, run `storage upgrade` again to apply any
 186  new updates.
 187  
 188  = Next Steps =
 189  
 190  Continue by:
 191  
 192    - setting up your admin account and login/registration with
 193      @{article:Configuring Accounts and Registration}; or
 194    - understanding advanced configuration topics with
 195      @{article:Configuration User Guide: Advanced Configuration}; or
 196    - configuring a preamble script to set up the environment properly behind a
 197      load balancer, or adjust rate limiting with
 198      @{article:Configuring a Preamble Script}; or
 199    - configuring where uploaded files and attachments will be stored with
 200      @{article:Configuring File Storage}; or
 201    - configuring Phabricator so it can send mail with
 202      @{article:Configuring Outbound Email}; or
 203    - configuring inbound mail with @{article:Configuring Inbound Email}; or
 204    - importing repositories with @{article:Diffusion User Guide}; or
 205    - learning about daemons with @{article:Managing Daemons with phd}; or
 206    - learning about notification with
 207      @{article:Notifications User Guide: Setup and Configuration}; or
 208    - configuring backups with
 209      @{article:Configuring Backups and Performing Migrations}; or
 210    - contributing to Phabricator with @{article:Contributor Introduction}.