This document describes how to adjust a standard development install of Phabricator so you can work with [[ phacility_cluster | Phacility Cluster ]] extensions and the Instances application.
Overview
======
This document will guide you through expanding a standard Phabricator install in a development environment (normally, one created by following the installation guide) to include the Phacility cluster and instance extensions.
Code Layout
======
Assuming your development directory is `phacility/`, check out these repositories:
- rCORE, as `core/`.
- rSAAS, as `instances/`.
- rSERVICES, as `services/`.
Next, move all repositories (`instances`, `services`, `phabricator`, `arcanist`, `libphutil`) except rCORE into `phacility/core/lib/`. This should give you this directory structure:
phacility/
core/
...
lib/
arcanist/
instances/
libphutil/
phabricator/
services/
...
For convenience, you may want to symlink everything back to the top level. This may also let you make fewer adjustments to webserver configuration. So you'll end up with this at top level:
phacility/
arcanist -> core/lib/arcanist
core/
instances -> core/lib/instances
libphutil -> core/lib/libphutil
phabricator -> core/lib/phabricator
services -> core/lib/services
You could probably swap this and leave the real directories at top level and just symlink them into `core/lib` if you want and are feeling ambitious.
Hosts File
======
Your local instance will become `http://local.phacility.com/`. You must use this host name, specifically. To make sure this works, add this to your `/etc/hosts` file:
127.0.0.1 local.phacility.com
If your local machine and development server aren't the same machine, make the edit on your local machine but use the development server's IP address instead.
Once setup is complete, you'll be able to use the Instances application to allocate local instances as long as they start with "local". Other instances don't have special behavior and won't work.
To support this, add entries like these to your `/etc/hosts` file:
```
127.0.0.1 locala.phacility.com
127.0.0.1 localb.phacility.com
127.0.0.1 localc.phacility.com
127.0.0.1 locald.phacility.com
127.0.0.1 locale.phacility.com
127.0.0.1 localf.phacility.com
...
```
You can add as many of these as you think you'll need, just make sure the instance names start with "local".
Load Libraries
======
To tell Phabricator to load the Phacility libraries, run this command:
phabricator/ $ ./bin/config set load-libraries '["instances/src", "services/src"]'
If you run other local extensions, this might overwrite them. You can use `config get` to check before adjusting the value.
Cluster Config
=======
You'll also need to define `cluster.addresses`:
phabricator/ $ ./bin/config set cluster.addresses '["127.0.0.1/32"]'
This sets your local "cluster" to only include the machine itself.
Environmental Variable
======
You'll need to set `PHABRICATOR_INSTANCE=local` for scripts to continue working. If you don't, they'll exit with an error about `PHABRICATOR_INSTANCE` not being set.
On OSX, you can add this to your `~/.profile`:
export PHABRICATOR_INSTANCE=local
After making the addition, open a new shell window for it to take effect.
If you want to run scripts in the context of some other instance, you can adjust the environmental variable on the command line. For example, this will report the storage status of the `localq` instance:
phabricator/ $ PHABRICATOR_INSTANCE=localq ./bin/storage status
Adjust Webserver Config
======
Depending on how your webserver is set up, you may need to change some of the rules to make sure the new domains (`local.phacility.com`, `locala.phacility.com`, etc.) get handled correctly. Exactly how to do this depends on which webserver you're using and how you set up the rules for it.
Initialize or Migrate Databases
======
Your "local" instance will use the "local" storage namespace, which will initially be empty. You can either move your old databases to this namespace (by renaming them all, e.g. rename `phabricator_user` to `local_user`) or use `bin/storage upgrade` to start fresh.
Check Progress
======
If you've done everything correctly so far, everything except the Instances application should now work normally when accessed at `http://local.phacility.com`. The Instances application requires some additional configuration.