Developer Setup

Updated 2,241 Days AgoPublic

Actions

This document describes how to adjust a standard development install of Phabricator so you can work with 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) except rCORE into phacility/core/lib/. This should give you this directory structure:

phacility/
  core/
    ...
    lib/
      arcanist/
      instances/
      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
  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:

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 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.

Almanac Device: Add Public SSH Key

On daemon.phacility.net add /path/to/core/conf/keys/daemon.pub as an SSH key. Once added, you will need to trust the key from the command-line by running ./bin/almanac trust-key --id 2 (replace 2 with the id number of the newly added key).

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 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: Support Application

Configure these settings in Applications → Support → Help/Options:

• Can Manage Support: Set to "Administrators" and the instance-client account. This is operational access to the web UI.

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.