2011-02-11 23:58:45 +01:00
|
|
|
@title Installation Guide
|
2011-05-12 17:15:02 +02:00
|
|
|
@group intro
|
2011-02-11 23:58:45 +01:00
|
|
|
|
|
|
|
This document contains basic install instructions to get Phabricator up and
|
|
|
|
running.
|
|
|
|
|
2014-11-07 19:17:21 +01:00
|
|
|
Overview
|
|
|
|
========
|
|
|
|
|
|
|
|
Phabricator is a LAMP (Linux, Apache, MySQL, PHP) application. To install
|
|
|
|
Phabricator, you will need:
|
|
|
|
|
|
|
|
- a normal computer to install it on (shared hosts and unusual environments
|
|
|
|
are not supported) running some flavor of Linux or a similar OS;
|
|
|
|
- a domain name (like `phabricator.mycompany.com`);
|
|
|
|
- basic sysadmin skills;
|
|
|
|
- Apache, nginx, or another webserver;
|
|
|
|
- PHP, MySQL, and Git.
|
|
|
|
|
|
|
|
The remainder of this document details these requirements.
|
|
|
|
|
|
|
|
Installation Requirements
|
|
|
|
=========================
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2013-10-25 17:58:42 +02:00
|
|
|
You will need **a computer**. Options include:
|
|
|
|
|
|
|
|
- **A Normal Computer**: This is strongly recommended. Many installs use a VM
|
|
|
|
in EC2. Phabricator installs properly and works well on a normal computer.
|
|
|
|
- **A Shared Host**: This may work, but is not recommended. Many shared
|
|
|
|
hosting environments have restrictions which prevent some of Phabricator's
|
2014-11-07 19:17:21 +01:00
|
|
|
features from working. Consider using a normal computer instead. We do not
|
|
|
|
support shared hosts.
|
2013-10-25 17:58:42 +02:00
|
|
|
- **A SAN Appliance, Network Router, Gaming Console, Raspberry Pi, etc.**:
|
|
|
|
Although you may be able to install Phabricator on specialized hardware, it
|
|
|
|
is unlikely to work well and will be difficult for us to support. Strongly
|
2014-11-07 19:17:21 +01:00
|
|
|
consider using a normal computer instead. We do not support specialized
|
|
|
|
hardware.
|
2013-10-25 17:58:42 +02:00
|
|
|
- **A Toaster, Car, Firearm, Thermostat, etc.**: Yes, many modern devices now
|
|
|
|
have embedded computing capability. We live in interesting times. However,
|
|
|
|
you should not install Phabricator on these devices. Instead, install it on
|
2014-11-07 19:17:21 +01:00
|
|
|
a normal computer. We do not support installing on noncomputing devices.
|
2013-10-25 17:58:42 +02:00
|
|
|
|
2014-03-16 21:00:20 +01:00
|
|
|
To install the Phabricator server software, you will need an **operating
|
2014-11-07 19:17:21 +01:00
|
|
|
system** on your normal computer which is **not Windows**. Note that the
|
|
|
|
command line interface //does// work on Windows, and you can //use//
|
|
|
|
Phabricator from any operating system with a web browser. However, the server
|
2014-03-16 21:00:20 +01:00
|
|
|
software does not run on Windows. It does run on most other operating systems,
|
|
|
|
so choose one of these instead:
|
2013-10-25 17:58:42 +02:00
|
|
|
|
|
|
|
- **Linux**: Most installs use Linux.
|
|
|
|
- **Mac OS X**: Mac OS X is an acceptable flavor of Linux.
|
|
|
|
- **FreeBSD**: While FreeBSD is certainly not a flavor of Linux, it is a fine
|
|
|
|
operating system possessed of many desirable qualities, and Phabricator will
|
|
|
|
install and run properly on FreeBSD.
|
|
|
|
- **Solaris, etc.**: Other systems which look like Linux and quack like Linux
|
|
|
|
will generally work fine, although we may suffer a reduced ability to
|
|
|
|
support and resolve issues on unusual operating systems.
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2013-10-25 17:58:42 +02:00
|
|
|
Beyond an operating system, you will need **a webserver**.
|
|
|
|
|
|
|
|
- **Apache**: Many installs use Apache + `mod_php`.
|
|
|
|
- **nginx**: Many installs use nginx + `php-fpm`.
|
|
|
|
- **lighttpd**: `lighttpd` is less popular than Apache or nginx, but it
|
|
|
|
works fine.
|
|
|
|
- **Other**: Other webservers which can run PHP are also likely to work fine,
|
|
|
|
although these installation instructions will not cover how to set them up.
|
|
|
|
- **PHP Builtin Server**: You can use the builtin PHP webserver for
|
|
|
|
development or testing, although it should not be used in production.
|
|
|
|
|
|
|
|
You will also need:
|
|
|
|
|
2014-11-07 19:17:21 +01:00
|
|
|
- **MySQL**: You need MySQL. We strongly recommend MySQL 5.5 or newer.
|
2013-10-25 17:58:42 +02:00
|
|
|
- **PHP**: You need PHP 5.2 or newer.
|
|
|
|
|
|
|
|
You'll probably also need a **domain name**. In particular, you should read this
|
|
|
|
note:
|
|
|
|
|
|
|
|
NOTE: Phabricator must be installed on an entire domain. You can not install it
|
|
|
|
to a path on an existing domain, like `example.com/phabricator/`. Instead,
|
|
|
|
install it to an entire domain or subdomain, like `phabricator.example.com`.
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2014-11-07 19:17:21 +01:00
|
|
|
Level Requirements
|
|
|
|
==================
|
|
|
|
|
|
|
|
To install and administrate Phabricator, you'll need to be comfortable with
|
|
|
|
common system administration skills. For example, you should be familiar with
|
|
|
|
using the command line, installing software on your operating system of choice,
|
|
|
|
working with the filesystem, managing processes, dealing with permissions,
|
|
|
|
editing configuration files, and setting environment variables.
|
|
|
|
|
|
|
|
If you aren't comfortable with these skills, you can still try to perform an
|
|
|
|
install. The install documentation will attempt to guide you through what you
|
|
|
|
need to know. However, if you aren't very familiar or comfortable with using
|
|
|
|
this set of skills to troubleshoot and resolve problems, you may encounter
|
|
|
|
issues which you have substantial difficulty working through.
|
|
|
|
|
|
|
|
We assume users installing and administrating Phabricator are comfortable with
|
|
|
|
common system administration skills and concepts. If you aren't, proceed at
|
|
|
|
your own risk and expect that your skills may be tested.
|
|
|
|
|
|
|
|
Installing Required Components
|
|
|
|
==============================
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
If you are installing on Ubuntu or an RedHat derivative, there are install
|
|
|
|
scripts available which should handle most of the things discussed in this
|
|
|
|
document for you:
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2013-01-04 21:30:47 +01:00
|
|
|
- **RedHat Derivatives**:
|
|
|
|
<http://www.phabricator.com/rsrc/install/install_rhel-derivs.sh>
|
2012-04-09 23:23:10 +02:00
|
|
|
- **Ubuntu**: <http://www.phabricator.com/rsrc/install/install_ubuntu.sh>
|
2011-02-11 23:58:45 +01:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
If those work for you, you can skip directly to the
|
|
|
|
@{article:Configuration Guide}. These scripts are also available in the
|
2014-08-06 23:18:32 +02:00
|
|
|
`scripts/install` directory in the project itself.
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
Otherwise, here's a general description of what you need to install:
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
- git (usually called "git" in package management systems)
|
2012-01-17 01:05:00 +01:00
|
|
|
- Apache (usually "httpd" or "apache2") (or nginx)
|
2011-06-13 05:40:50 +02:00
|
|
|
- MySQL Server (usually "mysqld" or "mysql-server")
|
|
|
|
- PHP (usually "php")
|
2013-01-04 21:30:47 +01:00
|
|
|
- Required PHP extensions: mbstring, iconv, mysql (or mysqli), curl, pcntl
|
|
|
|
(these might be something like "php-mysql" or "php5-mysql")
|
2011-06-13 05:40:50 +02:00
|
|
|
- Optional PHP extensions: gd, apc (special instructions for APC are available
|
2011-06-26 20:21:25 +02:00
|
|
|
below if you have difficulty installing it), xhprof (instructions below,
|
|
|
|
you only need this if you are developing Phabricator)
|
2011-06-13 05:40:50 +02:00
|
|
|
|
|
|
|
If you already have LAMP setup, you've probably already got everything you need.
|
|
|
|
It may also be helpful to refer to the install scripts above, even if they don't
|
|
|
|
work for your system.
|
|
|
|
|
|
|
|
Now that you have all that stuff installed, grab Phabricator and its
|
|
|
|
dependencies:
|
2011-02-11 23:58:45 +01:00
|
|
|
|
|
|
|
$ cd somewhere/ # pick some install directory
|
2014-06-03 18:40:16 +02:00
|
|
|
somewhere/ $ git clone https://github.com/phacility/libphutil.git
|
|
|
|
somewhere/ $ git clone https://github.com/phacility/arcanist.git
|
|
|
|
somewhere/ $ git clone https://github.com/phacility/phabricator.git
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-06-13 16:58:02 +02:00
|
|
|
= Installing APC (Optional) =
|
2011-02-11 23:58:45 +01:00
|
|
|
|
|
|
|
Like everything else written in PHP, Phabricator will run much faster with APC
|
|
|
|
installed. You likely need to install "pcre-devel" first:
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-02-11 23:58:45 +01:00
|
|
|
sudo yum install pcre-devel
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
Then you have two options. Either install via PECL (try this first):
|
2011-02-11 23:58:45 +01:00
|
|
|
|
|
|
|
sudo yum install php-pear
|
|
|
|
sudo pecl install apc
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-06-13 05:40:50 +02:00
|
|
|
**If that doesn't work**, grab the package from PECL directly and follow the
|
|
|
|
build instructions there:
|
2011-02-11 23:58:45 +01:00
|
|
|
|
|
|
|
http://pecl.php.net/package/APC
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-02-11 23:58:45 +01:00
|
|
|
Installing APC is optional but **strongly recommended**, especially on
|
|
|
|
production hosts.
|
|
|
|
|
|
|
|
Once APC is installed, test that it is available by running:
|
|
|
|
|
|
|
|
php -i | grep apc
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-02-11 23:58:45 +01:00
|
|
|
If it doesn't show up, add:
|
|
|
|
|
|
|
|
extension=apc.so
|
2011-05-08 22:25:39 +02:00
|
|
|
|
2011-02-11 23:58:45 +01:00
|
|
|
..to "/etc/php.d/apc.ini" or the "php.ini" file indicated by "php -i".
|
|
|
|
|
2011-06-30 04:45:12 +02:00
|
|
|
= Updating Phabricator =
|
|
|
|
|
Make SQL patch management DAG-based and provide namespace support
Summary:
This addresses three issues with the current patch management system:
# Two people developing at the same time often pick the same SQL patch number, and then have to go rename it. The system catches this, but it's silly.
# Second/third-party developers can't use the same system to manage auxiliary storage they may want to add.
# There's no way to build mock databases for unit tests that need to do reads.
To resolve these things, you can now name your patches whatever you want and conflicts are just merge conflicts, which are less of a pain to fix than filename conflicts.
Dependencies are now a DAG, with implicit dependencies created on the prior patch if no dependencies are specified. Developers can add new concrete subclasses of `PhabricatorSQLPatchList` to add storage management, and define the dependency branchpoint of their patches so they apply in the correct order (although, generally, they should not depend on the mainline patches, presumably).
The commands `storage upgrade --namespace test1234` and `storage destroy --namespace test1234` will allow unit tests to build and destroy MySQL storage.
A "quickstart" mode allows an upgrade from scratch in ~1200ms. Destruction takes about 200ms. These seem like fairily reasonable costs to actually use in tests. Building from scratch patch-by-patch takes about 6000ms.
Test Plan:
- Created new databases from scratch with and without quickstart in a separate test namespace. Pointed the webapp at the test namespaces, browsed around, everything looked good.
- Compared quickstart and no-quickstart dump states, they're identical except for mysqldump timestamps and a few similar things.
- Upgraded a legacy database to the new storage format.
- Destroyed / dumped storage.
Reviewers: edward, vrana, btrahan, jungejason
Reviewed By: btrahan
CC: aran, nh
Maniphest Tasks: T140, T345
Differential Revision: https://secure.phabricator.com/D2323
2012-04-30 16:54:00 +02:00
|
|
|
Since Phabricator is under active development, you should update frequently. To
|
|
|
|
update Phabricator:
|
|
|
|
|
2013-12-31 01:47:05 +01:00
|
|
|
- Stop the webserver (including `php-fpm`, if you use it).
|
2013-01-22 19:32:26 +01:00
|
|
|
- Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`.
|
Make SQL patch management DAG-based and provide namespace support
Summary:
This addresses three issues with the current patch management system:
# Two people developing at the same time often pick the same SQL patch number, and then have to go rename it. The system catches this, but it's silly.
# Second/third-party developers can't use the same system to manage auxiliary storage they may want to add.
# There's no way to build mock databases for unit tests that need to do reads.
To resolve these things, you can now name your patches whatever you want and conflicts are just merge conflicts, which are less of a pain to fix than filename conflicts.
Dependencies are now a DAG, with implicit dependencies created on the prior patch if no dependencies are specified. Developers can add new concrete subclasses of `PhabricatorSQLPatchList` to add storage management, and define the dependency branchpoint of their patches so they apply in the correct order (although, generally, they should not depend on the mainline patches, presumably).
The commands `storage upgrade --namespace test1234` and `storage destroy --namespace test1234` will allow unit tests to build and destroy MySQL storage.
A "quickstart" mode allows an upgrade from scratch in ~1200ms. Destruction takes about 200ms. These seem like fairily reasonable costs to actually use in tests. Building from scratch patch-by-patch takes about 6000ms.
Test Plan:
- Created new databases from scratch with and without quickstart in a separate test namespace. Pointed the webapp at the test namespaces, browsed around, everything looked good.
- Compared quickstart and no-quickstart dump states, they're identical except for mysqldump timestamps and a few similar things.
- Upgraded a legacy database to the new storage format.
- Destroyed / dumped storage.
Reviewers: edward, vrana, btrahan, jungejason
Reviewed By: btrahan
CC: aran, nh
Maniphest Tasks: T140, T345
Differential Revision: https://secure.phabricator.com/D2323
2012-04-30 16:54:00 +02:00
|
|
|
- Run `phabricator/bin/storage upgrade`.
|
2013-12-31 01:47:05 +01:00
|
|
|
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
|
Make SQL patch management DAG-based and provide namespace support
Summary:
This addresses three issues with the current patch management system:
# Two people developing at the same time often pick the same SQL patch number, and then have to go rename it. The system catches this, but it's silly.
# Second/third-party developers can't use the same system to manage auxiliary storage they may want to add.
# There's no way to build mock databases for unit tests that need to do reads.
To resolve these things, you can now name your patches whatever you want and conflicts are just merge conflicts, which are less of a pain to fix than filename conflicts.
Dependencies are now a DAG, with implicit dependencies created on the prior patch if no dependencies are specified. Developers can add new concrete subclasses of `PhabricatorSQLPatchList` to add storage management, and define the dependency branchpoint of their patches so they apply in the correct order (although, generally, they should not depend on the mainline patches, presumably).
The commands `storage upgrade --namespace test1234` and `storage destroy --namespace test1234` will allow unit tests to build and destroy MySQL storage.
A "quickstart" mode allows an upgrade from scratch in ~1200ms. Destruction takes about 200ms. These seem like fairily reasonable costs to actually use in tests. Building from scratch patch-by-patch takes about 6000ms.
Test Plan:
- Created new databases from scratch with and without quickstart in a separate test namespace. Pointed the webapp at the test namespaces, browsed around, everything looked good.
- Compared quickstart and no-quickstart dump states, they're identical except for mysqldump timestamps and a few similar things.
- Upgraded a legacy database to the new storage format.
- Destroyed / dumped storage.
Reviewers: edward, vrana, btrahan, jungejason
Reviewed By: btrahan
CC: aran, nh
Maniphest Tasks: T140, T345
Differential Revision: https://secure.phabricator.com/D2323
2012-04-30 16:54:00 +02:00
|
|
|
|
|
|
|
For more details, see @{article:Configuration Guide}. You can use a script
|
|
|
|
similar to this one to automate the process:
|
2011-06-30 04:45:12 +02:00
|
|
|
|
2012-04-09 23:23:10 +02:00
|
|
|
http://www.phabricator.com/rsrc/install/update_phabricator.sh
|
2011-06-30 04:45:12 +02:00
|
|
|
|
2011-02-11 23:58:45 +01:00
|
|
|
= Next Steps =
|
|
|
|
|
2011-05-12 17:15:02 +02:00
|
|
|
Continue by:
|
|
|
|
|
|
|
|
- configuring Phabricator with the @{article:Configuration Guide}.
|