Page MenuHomePhorge

Update From Phabricator
Updated 21 Days AgoPublic

How To Migrate from Phabricator To Phorge

The process of migrating from Phabricator to Phorge is very similar the Upgrading Process, except that you'll be switching to a different remote.

Assumptions and Requirements

This document makes several assumptions about your install:

  1. We assume you've you've installed Phabricator using the official, supported instructions in https://secure.phabricator.com/book/phabricator/article/installation_guide/. That is, we assume you've used git clone to get the code from Phacility's GitHub mirrors.
  2. We assume you've made no local changes ("fork") to the code. If you've added a library that's fine, but we assume no changes to the phabricator and arcanist code bases.

If you have made local changes to your install, then we assume you're comfortable enough with git to adapt.

Process

We won't rename any directories here - while new installs will have a phorge/ and arcanist/ directories, you'll keep phabricator/ and arcanist/. This way, your existing scripts and tools should keep working. This is something to keep in mind during migration, if you want to rename these directories in the future. You can make this change yourself if you feel comfortable to.

There are also many internal references to the phabricator term - we'll be keeping those as well.

Get Current Version

First, you'll want to check the current version of your Phabricator install. Phabricator and Phorge use Git commit hashes as "version". You can see your current versions of phabricator and arcanist packages by visiting your install /config page.

You'll want to be reasonably up-to-date before migrating - see Phabricator's Changelogs for details. We highly recommend updating at least to an early 2022 version.

Currently, Phorge is up to date with these Phabricator commits:

RepositoryCommit hashDateComment
Phabricator9426765a2c6aJun 14 2022Flatten "RemarkupValue" objects when setting field defaults for custom forms
Arcanist85c953ebe4a6May 18 2022Fix a PHP 8.1 repository marker issue in Mercurial

If your install is more advanced then these commits, the best approach is probably to wait for Phorge to catch up (or ask a Core Team member to update).

Depending on how long it's been since you've last updated, there may be some breaking changes added to Phorge - you may want to check the Changelog. This guide is up-to-date up to 2022 Week 37.

Updating

1. Stop the webserver and daemons.
2. Backup your install - Database and files storage.
3. Update the origin address in each repository and take changes:
$ cd ./phabricator/

# This will print out `master` or `stable` - it's the branch you're using:
$ git rev-parse --abbrev-ref '@{u}'

$ git remote rename origin old-origin
$ git remote add origin https://we.phorge.it/source/phorge.git
$ git fetch origin

# This creates a backup of your current state:
$ git branch last_known_good HEAD

# Remove some files we broke in Aphlict - we'll update that later.
$ rm -f ./support/aphlict/server/package-lock.json  ./support/aphlict/server/package.json

# Configure your new remote: You can use `origin/stable` instead that's the branch you've been using.
$ git branch --set-upstream-to=origin/master
$ git pull

# Repeat for Arcanist directory:
$ cd ../arcanist/
$ git remote rename origin old-origin
$ git remote add origin https://we.phorge.it/source/arcanist.git
$ git fetch origin
$ git branch last_known_good HEAD

# Configure your new remote: You can use `origin/stable` instead that's the branch you've been using.
$ git branch --set-upstream-to=origin/master

# Reset your working copy of Archanist to the latest remote: You can use `origin/stable` instead that's the branch you've been using. This may remove any files you've changed in your working copy.
$ git reset --hard origin/master
# And again for Phorge
$ cd ../phabricator/
# Reset your working copy of Phorge to the latest remote: You can use `origin/stable` instead that's the branch you've been using. This may remove any files you've changed in your working copy.
$ git reset --hard origin/master
4. Update Some Configurations
IMPORTANT: You may have already changed some of these configurations in your install to non-default values. Make sure not to change them to wrong values! You can list existing values by running ./bin/config get <config key>.

The default values of these configuration values may have changed from Phabricator to Phorge, so here we'll explicitly set them to their previous defaults.

Update these configs by running ./bin/config set <config key> <value> in the phabricator directory, eg:

$ ./bin/config set storage.default-namespace phabricator
Config keyOld defaultNew DefaultComment
storage.default-namespacephabricatorunchangedMay be changed soon. Set this one now!
5. Re-install Aphlict

Aphlict is the Notifications Server, allowing for "real-time" notifications to show up on pages.

We've changed Aphlict's installation instructions in T15019.
Aphlict still requires node and npm.

$ cd ./phabricator/support/aphlict/server/
$ rm -rf node_modules/
$ npm install --no-save
$ cd ../../../../

Upgrade Storage and Restarting

Just like a regular update, you should run phabricator/bin/storage upgrade at this point.

IMPORTANT: This is the point-of-no-return. Once you've change the database schema, there's no going back to an earlier version. You should have made a backup before starting the update.

Now run phabricator/bin/cache purge --all to clear any lingering static assets that should be updated automatically.

Next, start the daemons and restart the webserver as instructed in Upgrading Process.

At this point, you should be back up and running the latest version of Phorge. Further upgrades should be handled normally.

Last Author
Cigaryno
Last Edited
Sat, Nov 5, 09:55

Event Timeline

avivey published a new version of this document.
avivey added a subscriber: avivey.

The aphlict instructions are confusing.
Why do we run npm install when we have previously deleted the package.json file from that directory?

Why do we run npm install when we have previously deleted the package.json file from that directory?

Because we changed the Aphlict setup in T15019 , and the new setup requires that we run npm install. Deleting the old package.json is required to prevent git conflicts.

Unfortunately, running npm install in a directory that does not contain a package.json file does exactly nothing.
Maybe the instructions are wrong and we're supposed to delete node_modules/ and package-lock.json but not package.json which I see actually got added in rP2258ba8535d57081582add7375c31837ac2f26f3.

Now this makes sense to me:

root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# cat package.json 
{
  "name": "aphlict-server",
  "description": "Phorge's aphlict's server",
  "main": "aphlict_server.js",
  "directories": {
    "lib": "lib"
  },
  "license": "Apache-2.0",
  "dependencies": {
    "ws": "^7.5.0"
  }
}
root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# npm i --no-save
npm WARN aphlict-server@ No repository field.

added 1 package from 1 contributor and audited 1 package in 1.05s
found 0 vulnerabilities

@kwisatz - did you actually try to follow the instructions and ran into a problem, or are you just speculating?

@avivey I'm not here to troll, I'm sincerely puzzled, even more by comparing T15019 to the instructions above.

I followed the instructions to the letter. Here's what happens if I do it again:

root@kerberos:/var/www/phabricator# cd ./phabricator/support/aphlict/server/
root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# rm -f package-lock.json package.json
root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# rm -rf node_modules/
root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# npm install --no-save
npm WARN enoent ENOENT: no such file or directory, open '/var/www/phabricator/phabricator/support/aphlict/server/package.json'
npm WARN server No description
npm WARN server No repository field.
npm WARN server No README data
npm WARN server No license field.

up to date in 6.169s
found 0 vulnerabilities

root@kerberos:/var/www/phabricator/phabricator/support/aphlict/server# cd ../../../../

I'm not used to running npm i without a package name in a directory that does not contain a package.json file either and I'm confused by this part:

npm WARN enoent ENOENT: no such file or directory, open '/var/www/phabricator/phabricator/support/aphlict/server/package.json'

So:

  1. What is supposed to be the effect of running npm i here ? How can the user verify it was a success?
  2. If T15019 introduces a package.json then why do the instructions call for deleting it?

ah, I see the error now.
yes, that's a typo - it was carried over from an earlier version of the document.
in phase 5, only node-modules should be removed, not the package files.
thank you for reporting, and sorry I was being harsh - I forgot I split this section and only looked at the primary blob of commands.

@avivey no worries and you're welcome. I was afraid I was maybe in the process of making an ass out of myself…

What if you upgrade a heavily modified (forked) Phabricator to the vanilla Phorge?

What if you upgrade a heavily modified (forked) Phabricator to the vanilla Phorge?

You'll probably want to do some git rebase (or merge) off the latest Phorge master, and follow the rest of the instructions.
I'm hoping if you forked it, you're comfortable enough with git and php to handle the update.

Cigaryno published a new version of this document.Mon, Oct 31, 18:39
Cigaryno published a new version of this document.