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**: Phabricator will not work with the builtin
  68     webserver because Phabricator depends on making requests to itself on some
  69     workflows, and the builtin webserver is single-threaded.
  70
  71 You will also need:
  72
  73   - **MySQL**: You need MySQL. We strongly recommend MySQL 5.5 or newer.
  74   - **PHP**: You need PHP 5.5 or newer.
  75
  76 You'll probably also need a **domain name**. In particular, you should read this
  77 note:
  78
  79 NOTE: Phabricator must be installed on an entire domain. You can not install it
  80 to a path on an existing domain, like `example.com/phabricator/`. Instead,
  81 install it to an entire domain or subdomain, like `phabricator.example.com`.
  82
  83 Level Requirements
  84 ==================
  85
  86 To install and administrate Phabricator, you'll need to be comfortable with
  87 common system administration skills. For example, you should be familiar with
  88 using the command line, installing software on your operating system of choice,
  89 working with the filesystem, managing processes, dealing with permissions,
  90 editing configuration files, and setting environment variables.
  91
  92 If you aren't comfortable with these skills, you can still try to perform an
  93 install. The install documentation will attempt to guide you through what you
  94 need to know. However, if you aren't very familiar or comfortable with using
  95 this set of skills to troubleshoot and resolve problems, you may encounter
  96 issues which you have substantial difficulty working through.
  97
  98 We assume users installing and administrating Phabricator are comfortable with
  99 common system administration skills and concepts. If you aren't, proceed at
 100 your own risk and expect that your skills may be tested.
 101
 102 Installing Required Components
 103 ==============================
 104
 105 Here's a general description of what you need to install:
 106
 107   - git (usually called "git" in package management systems)
 108   - Apache (usually "httpd" or "apache2") (or nginx)
 109   - MySQL Server (usually "mysqld" or "mysql-server")
 110   - PHP (usually "php")
 111   - Required PHP extensions: mbstring, iconv, mysql (or mysqli), curl, pcntl
 112     (these might be something like "php-mysql" or "php5-mysqlnd")
 113   - Optional PHP extensions: gd
 114
 115 If you already have LAMP setup, you've probably already got everything you need.
 116 It may also be helpful to refer to the install scripts above, even if they don't
 117 work for your system.
 118
 119 Now that you have all that stuff installed, grab Phabricator and its
 120 dependencies:
 121
 122   $ cd somewhere/ # pick some install directory
 123   somewhere/ $ git clone https://github.com/phacility/arcanist.git
 124   somewhere/ $ git clone https://github.com/phacility/phabricator.git
 125
 126 Next Steps
 127 ==========
 128
 129 Continue by:
 130
 131   - configuring Phabricator with the @{article:Configuration Guide}; or
 132   - learning how to keep Phabricator up to date with
 133     @{article:Upgrading Phabricator}.