= How To Migrate from Phabricator To Phorge
The process of migrating from Phabricator to Phorge is very similar the [[ https://we.phorge.it/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 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 [[ https://secure.phabricator.com/w/changelog/ | 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:
| 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 |
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 [[ 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
$ git pull
$ git reset --hard HEAD
```
==== 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:
```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, start the daemons and restart the webserver as instructed in [[ https://we.phorge.it/book/phorge/article/upgrading/ | Upgrading Process ]].
At this point, you should be back up and running the latest version of Phorge. Further upgrades should be handled normally.