= How To Migrate from Phabricator To Phorge
The process of migrating from Phabricator to Phorge is very similar the [[ /book/phorge/article/upgrading/ | Upgrading Process ]], except that you'll be switching to a different remote.
== Assumptions and Requirements
This document makes several assumptions about your already-existing install:
1. We assume 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.
=== Find Your 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 [[ https://secure.phabricator.com/w/changelog/ | Phabricator's Changelogs ]] for details. We highly recommend updating at least to an early 2022 version.
Before considering a migration to Phorge, your Phabricator should be up to date, and have //at least// these upstream commits:
| Repository | Commit hash | Date | Comment |
|---------|---|---|---|
| Phabricator | `9426765a2c6a` | Jun 14 2022 |Flatten "RemarkupValue" objects when setting field defaults for custom forms |
| Arcanist | `85c953ebe4a6` | May 18 2022 | Fix a PHP 8.1 repository marker issue in Mercurial |
Note that since 2022, Phorge introduced 300+ commits, and Phabricator less than 30+ commits. We are generally aware of this situation (see [[ differences_between_phabricator_and_phorge/ ]]). If you are interested in a specific feature that is Phabricator-only, please contact Phorge to catch these.
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 [[ changelog | the Changelog ]]. This guide is up-to-date up to [[ changelog/2022.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:
```lang=shell
$ 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://github.com/phorgeit/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://github.com/phorgeit/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 Arcanist 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!
(NOTE) You can list your Config values by running `./bin/config list` and inspect a specific value with `./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:
```lang=shell
$ ./bin/config set storage.default-namespace phabricator
```
| Config key | Old default | New Default | Comment
|--|--|--|--|
| storage.default-namespace | `phabricator` | //unchanged// | May be changed soon. Set this one now!
==== 5. Re-install Aphlict
//Aphlict is the [[ https://we.phorge.it/book/phorge/article/notifications/ | 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`.
```lang=shell
$ 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, restart the daemons and the webserver as instructed in @{article:Upgrading Phorge}.
At this point, you should be back up and running the latest version of Phorge. Further upgrades should be handled normally.