[Summary view] [Print] [Text view]

   1  @title Installation Guide
   2  @group intro
   3  
   4  This document contains basic install instructions to get Phabricator up and
   5  running.
   6  
   7  Overview
   8  ========
   9  
  10  Phabricator is a LAMP (Linux, Apache, MySQL, PHP) application. To install
  11  Phabricator, you will need:
  12  
  13    - a normal computer to install it on (shared hosts and unusual environments
  14      are not supported) running some flavor of Linux or a similar OS;
  15    - a domain name (like `phabricator.mycompany.com`);
  16    - basic sysadmin skills;
  17    - Apache, nginx, or another webserver;
  18    - PHP, MySQL, and Git.
  19  
  20  The remainder of this document details these requirements.
  21  
  22  Installation Requirements
  23  =========================
  24  
  25  You will need **a computer**. Options include:
  26  
  27    - **A Normal Computer**: This is strongly recommended. Many installs use a VM
  28      in EC2. Phabricator installs properly and works well on a normal computer.
  29    - **A Shared Host**: This may work, but is not recommended. Many shared
  30      hosting environments have restrictions which prevent some of Phabricator's
  31      features from working. Consider using a normal computer instead. We do not
  32      support shared hosts.
  33    - **A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.**:
  34      Although you may be able to install Phabricator on specialized hardware, it
  35      is unlikely to work well and will be difficult for us to support. Strongly
  36      consider using a normal computer instead. We do not support specialized
  37      hardware.
  38    - **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
  39      have embedded computing capability. We live in interesting times. However,
  40      you should not install Phabricator on these devices. Instead, install it on
  41      a normal computer. We do not support installing on noncomputing devices.
  42  
  43  To install the Phabricator server software, you will need an **operating
  44  system** on your normal computer which is **not Windows**. Note that the
  45  command line interface //does// work on Windows, and you can //use//
  46  Phabricator from any operating system with a web browser. However, the server
  47  software does not run on Windows. It does run on most other operating systems,
  48  so choose one of these instead:
  49  
  50    - **Linux**: Most installs use Linux.
  51    - **Mac OS X**: Mac OS X is an acceptable flavor of Linux.
  52    - **FreeBSD**: While FreeBSD is certainly not a flavor of Linux, it is a fine
  53      operating system possessed of many desirable qualities, and Phabricator will
  54      install and run properly on FreeBSD.
  55    - **Solaris, etc.**: Other systems which look like Linux and quack like Linux
  56      will generally work fine, although we may suffer a reduced ability to
  57      support and resolve issues on unusual operating systems.
  58  
  59  Beyond an operating system, you will need **a webserver**.
  60  
  61    - **Apache**: Many installs use Apache + `mod_php`.
  62    - **nginx**: Many installs use nginx + `php-fpm`.
  63    - **lighttpd**: `lighttpd` is less popular than Apache or nginx, but it
  64      works fine.
  65    - **Other**: Other webservers which can run PHP are also likely to work fine,
  66      although these installation instructions will not cover how to set them up.
  67    - **PHP Builtin Server**: You can use the builtin PHP webserver for
  68      development or testing, although it should not be used in production.
  69  
  70  You will also need:
  71  
  72    - **MySQL**: You need MySQL. We strongly recommend MySQL 5.5 or newer.
  73    - **PHP**: You need PHP 5.2 or newer.
  74  
  75  You'll probably also need a **domain name**. In particular, you should read this
  76  note:
  77  
  78  NOTE: Phabricator must be installed on an entire domain. You can not install it
  79  to a path on an existing domain, like `example.com/phabricator/`. Instead,
  80  install it to an entire domain or subdomain, like `phabricator.example.com`.
  81  
  82  Level Requirements
  83  ==================
  84  
  85  To install and administrate Phabricator, you'll need to be comfortable with
  86  common system administration skills. For example, you should be familiar with
  87  using the command line, installing software on your operating system of choice,
  88  working with the filesystem, managing processes, dealing with permissions,
  89  editing configuration files, and setting environment variables.
  90  
  91  If you aren't comfortable with these skills, you can still try to perform an
  92  install. The install documentation will attempt to guide you through what you
  93  need to know. However, if you aren't very familiar or comfortable with using
  94  this set of skills to troubleshoot and resolve problems, you may encounter
  95  issues which you have substantial difficulty working through.
  96  
  97  We assume users installing and administrating Phabricator are comfortable with
  98  common system administration skills and concepts. If you aren't, proceed at
  99  your own risk and expect that your skills may be tested.
 100  
 101  Installing Required Components
 102  ==============================
 103  
 104  If you are installing on Ubuntu or an RedHat derivative, there are install
 105  scripts available which should handle most of the things discussed in this
 106  document for you:
 107  
 108    - **RedHat Derivatives**:
 109      <http://www.phabricator.com/rsrc/install/install_rhel-derivs.sh>
 110    - **Ubuntu**: <http://www.phabricator.com/rsrc/install/install_ubuntu.sh>
 111  
 112  If those work for you, you can skip directly to the
 113  @{article:Configuration Guide}. These scripts are also available in the
 114  `scripts/install` directory in the project itself.
 115  
 116  Otherwise, here's a general description of what you need to install:
 117  
 118    - git (usually called "git" in package management systems)
 119    - Apache (usually "httpd" or "apache2") (or nginx)
 120    - MySQL Server (usually "mysqld" or "mysql-server")
 121    - PHP (usually "php")
 122    - Required PHP extensions: mbstring, iconv, mysql (or mysqli), curl, pcntl
 123      (these might be something like "php-mysql" or "php5-mysql")
 124    - Optional PHP extensions: gd, apc (special instructions for APC are available
 125      below if you have difficulty installing it), xhprof (instructions below,
 126      you only need this if you are developing Phabricator)
 127  
 128  If you already have LAMP setup, you've probably already got everything you need.
 129  It may also be helpful to refer to the install scripts above, even if they don't
 130  work for your system.
 131  
 132  Now that you have all that stuff installed, grab Phabricator and its
 133  dependencies:
 134  
 135    $ cd somewhere/ # pick some install directory
 136    somewhere/ $ git clone https://github.com/phacility/libphutil.git
 137    somewhere/ $ git clone https://github.com/phacility/arcanist.git
 138    somewhere/ $ git clone https://github.com/phacility/phabricator.git
 139  
 140  = Installing APC (Optional) =
 141  
 142  Like everything else written in PHP, Phabricator will run much faster with APC
 143  installed. You likely need to install "pcre-devel" first:
 144  
 145    sudo yum install pcre-devel
 146  
 147  Then you have two options. Either install via PECL (try this first):
 148  
 149    sudo yum install php-pear
 150    sudo pecl install apc
 151  
 152  **If that doesn't work**, grab the package from PECL directly and follow the
 153  build instructions there:
 154  
 155  http://pecl.php.net/package/APC
 156  
 157  Installing APC is optional but **strongly recommended**, especially on
 158  production hosts.
 159  
 160  Once APC is installed, test that it is available by running:
 161  
 162    php -i | grep apc
 163  
 164  If it doesn't show up, add:
 165  
 166    extension=apc.so
 167  
 168  ..to "/etc/php.d/apc.ini" or the "php.ini" file indicated by "php -i".
 169  
 170  = Updating Phabricator =
 171  
 172  Since Phabricator is under active development, you should update frequently. To
 173  update Phabricator:
 174  
 175    - Stop the webserver (including `php-fpm`, if you use it).
 176    - Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`.
 177    - Run `phabricator/bin/storage upgrade`.
 178    - Restart the webserver (and `php-fpm`, if you stopped it earlier).
 179  
 180  For more details, see @{article:Configuration Guide}. You can use a script
 181  similar to this one to automate the process:
 182  
 183  http://www.phabricator.com/rsrc/install/update_phabricator.sh
 184  
 185  = Next Steps =
 186  
 187  Continue by:
 188  
 189    - configuring Phabricator with the @{article:Configuration Guide}.