src/docs/user/installation_guide.diviner

   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     [[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_rhel-derivs.sh
 110      | install_rhel-derivs.sh ]]
 111   - **Ubuntu**:
 112     [[ https://secure.phabricator.com/diffusion/P/browse/master/scripts/install/install_ubuntu.sh
 113      | install_ubuntu.sh ]]
 114
 115 If those work for you, you can skip directly to the
 116 @{article:Configuration Guide}. These scripts are also available in the
 117 `scripts/install` directory in the project itself.
 118
 119 Otherwise, here's a general description of what you need to install:
 120
 121   - git (usually called "git" in package management systems)
 122   - Apache (usually "httpd" or "apache2") (or nginx)
 123   - MySQL Server (usually "mysqld" or "mysql-server")
 124   - PHP (usually "php")
 125   - Required PHP extensions: mbstring, iconv, mysql (or mysqli), curl, pcntl
 126     (these might be something like "php-mysql" or "php5-mysqlnd")
 127   - Optional PHP extensions: gd, apc (special instructions for APC are available
 128     below if you have difficulty installing it), xhprof (instructions below,
 129     you only need this if you are developing Phabricator)
 130
 131 If you already have LAMP setup, you've probably already got everything you need.
 132 It may also be helpful to refer to the install scripts above, even if they don't
 133 work for your system.
 134
 135 Now that you have all that stuff installed, grab Phabricator and its
 136 dependencies:
 137
 138   $ cd somewhere/ # pick some install directory
 139   somewhere/ $ git clone https://github.com/phacility/libphutil.git
 140   somewhere/ $ git clone https://github.com/phacility/arcanist.git
 141   somewhere/ $ git clone https://github.com/phacility/phabricator.git
 142
 143 = Installing APC (Optional) =
 144
 145 Like everything else written in PHP, Phabricator will run much faster with APC
 146 installed. You likely need to install "pcre-devel" first:
 147
 148   sudo yum install pcre-devel
 149
 150 Then you have two options. Either install via PECL (try this first):
 151
 152   sudo yum install php-pear
 153   sudo pecl install apc
 154
 155 **If that doesn't work**, grab the package from PECL directly and follow the
 156 build instructions there:
 157
 158 http://pecl.php.net/package/APC
 159
 160 Installing APC is optional but **strongly recommended**, especially on
 161 production hosts.
 162
 163 Once APC is installed, test that it is available by running:
 164
 165   php -i | grep apc
 166
 167 If it doesn't show up, add:
 168
 169   extension=apc.so
 170
 171 ..to "/etc/php.d/apc.ini" or the "php.ini" file indicated by "php -i".
 172
 173 = Next Steps =
 174
 175 Continue by:
 176
 177   - configuring Phabricator with the @{article:Configuration Guide}; or
 178   - learning how to keep Phabricator up to date with
 179     @{article:Upgrading Phabricator}.