@title User Guide: Phabricator Clusters
@group config

Guide on scaling Phabricator across multiple machines.

Overview
========

IMPORTANT: Phabricator clustering is in its infancy and does not work at all
yet. This document is mostly a placeholder.

IMPORTANT: DO NOT CONFIGURE CLUSTER SERVICES UNLESS YOU HAVE **TWENTY YEARS OF
EXPERIENCE WITH PHABRICATOR** AND **A MINIMUM OF 17 PHABRICATOR PHDs**. YOU
WILL BREAK YOUR INSTALL AND BE UNABLE TO REPAIR IT.

See also @{article:Almanac User Guide}.


Managing Cluster Configuration
==============================

Cluster configuration is managed primarily from the **Almanac** application.

To define cluster services and create or edit cluster configuration, you must
have the **Can Manage Cluster Services** application permission in Almanac. If
you do not have this permission, all cluster services and all connected devices
will be locked and not editable.

The **Can Manage Cluster Services** permission is stronger than service and
device policies, and overrides them. You can never edit a cluster service if
you don't have this permission, even if the **Can Edit** policy on the service
itself is very permissive.


Locking Cluster Configuration
=============================

IMPORTANT: Managing cluster services is **dangerous** and **fragile**.

If you make a mistake, you can break your install. Because the install is
broken, you will be unable to load the web interface in order to repair it.

IMPORTANT: Currently, broken clusters must be repaired by manually fixing them
in the database. There are no instructions available on how to do this, and no
tools to help you. Do not configure cluster services.

If an attacker gains access to an account with permission to manage cluster
services, they can add devices they control as database servers. These servers
will then receive sensitive data and traffic, and allow the attacker to
escalate their access and completely compromise an install.