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 '["core/src", "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.
Make core/tmp Writable
======
Run this:
$ chmod o+w /path/to/core/tmp
Create a Symlink to keystore
======
$ ln -s /path/to/core/conf/keys/ /path/to/core/conf/keystore
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.
Instances: Almanac
======
To get Instances working, we need to set up a lot of stuff in Almanac. We're going to define a network (`phacility.net`), to contain all the services and devices, then add your machine as a device (`local.phacility.net`). We'll also create a pseudo-device named `daemon.phacility.net` which is used for authentication.
After creating the device, we'll create a Database service, a Repository service, and a pseudo-service for authentication.
This simulates deploying a machine into the DB tier, a machine into the Repo tier, and letting the daemons make remote calls. But we'll bind all the services to your local machine, so all of the calls will really be happening locally.
In detail, create these Almanac resources in order:
| Resource Type | Name | Kind | Notes |
|---|---|---|---|
| Network | `phacility.net` | | Create this first. |
| Device | `daemon.phacility.net` | | Then add interfaces on `127.0.0.1`... |
| Interface | `daemon.phacility.net:80` | | On `phacility.net` network. Port doesn't really matter. |
| Device | `local.phacility.net` | | Then add interfaces on `127.0.0.1`... |
| Interface | `local.phacility.net:80` | | On `phacility.net`, for HTTP. |
| Interface | `local.phacility.net:3306` | | On `phacility.net`, for MySQL. |
| Interface | `local.phacility.net:22` | | On `phacility.net`, if you plan to configure SSH VCS (or do this later). You can use a custom port. |
| Service | `services.phacility.net` | Custom | Bind `services.phacility.net` to `daemon.phacility.net`. |
| Service | `dbx001.phacility.net` | Cluster Database | Bind `local.phacility.net:3306`. Add `instances.open` property to service with value "1". |
| Service | `repox001.phacility.net` | Cluster Repository | Bind `local.phacility.net:80`. Edit binding, add property "protocol" with value "http". Add `instances.open` property to service with value "1". If configuring SSH, bind `local.phacility.net:22` (or custom port). Edit binding, add property "protocol" with value "ssh". |
You'll be able to check that you got this right in a minute. For now, configure the other prerequisites.
Instances: Phortune
=======
You need to create a Merchant named "Phacility", exactly, in {nav Phortune > Switch Accounts > View All Merchants > Create Merchant}. It doesn't need any special configuration.
Instances: Instance Client
=======
Create a new bot account named `instance-client`. Add `/path/to/core/conf/keys/client.pub` in Settings as a recognized SSH key.
This will allow instances to connect to the administrative server over Conduit.
Instances: Register Device
=======
Run this command to register your device:
phabricator/ $ ./bin/almanac register --device daemon.phacility.net --identify-as local.phacility.net --private-key /path/to/core/conf/keys/daemon.key
This will allow daemons to make service calls to instances.
Instances: Instances Application
========
Configure these settings in {nav Applications > Instances > Help/Options}:
- **Can Manage Instances**: Set to "Administrators" and the `instance-client` account. This is operational access to the web UI.
- **Can Access Instance Auth**: Set to the `instance-client` user only.
Instances: Create device.id File
=======
Create a new file at `/path/to/core/conf/device.id` and write `local.phacility.com` as its content.
Instances: Test Configuration
=======
To test configuration, create a new instance in the Instances application. If everything is set up correctly, it should spin up normally and you should be able to use "Manage Instance" to access the administrative interface.