- Code Layout
- Hosts File
- Load Libraries
- Cluster Config
- Environmental Variable
- Adjust Webserver Config
- Initialize or Migrate Databases
- Make core/tmp Writable
- Create a Symlink to keystore
- Check Progress
- Instances: Almanac
- Instances: Phortune
- Instances: Instance Client
- Almanac Device: Add Public SSH Key
- Instances: Register Device
- Instances: Instances Application
- Instances: Support Application
- Instances: Create device.id File
- Instances: Test Configuration
This document describes how to adjust a standard development install of Phabricator so you can work with Phacility Cluster extensions and the Instances application.
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.
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.
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:
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".
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.
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.
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:
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
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.
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.
$ chmod o+w /path/to/core/tmp
$ ln -s /path/to/core/conf/keys/ /path/to/core/conf/keystore
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.
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:
|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.
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.
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.
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).
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.
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.
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.
Create a new file at /path/to/core/conf/device.id and write local.phacility.com as its content.
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.