Phabricator: Difference between revisions

Latest revision as of 13:22, 18 October 2023

DEAD

I put a lot of effort into this old girl.... and then she up and left me... (Epriestly could only give so much of himself...) Kill it and move on to GitLab...

NOTE I moved the GLAM 106- apache file from sites-enabled to sites-available. Hopefully that is enough to put it to bed.

OLD

Phabricator is a solid agile project manager and issue tracker, with a customizable workflow.

My Workflow

WORKFLOW		Description
Workflow columns	Backlog => In Progress	There is a third column Fixed that can be shown, it's nice to move Resolved items there on occasion to clean up the board.
Create a task	Click dropdown on Backlog, select Create Task.	Or you can click the large + in the top-right toolbar, select Create Task, and assign the correct Project in the tags box.
Start a task	Drag it from Backlog to In Progress.	Drop above an existing task so the priority will be automatically set. If this is not possible, you need to manually change Priority to High so that the CI dashboard shows the task.
Finish a task	Change Status to Resolved.	This will hide the task on the CI dashboard. It will also immediately remove the task from the board if you are only showing Open statuses. You can also drag the task from In Progress to Fixed; this has no real effect on the task, but will keep your board better organized.

Tips

If you are viewing a board by priority, and drag, the dropped task will have its priority automatically adjusted to fit in drag zone. This works great if you can drag a new item from Backlog to a spot above an existing In Progress item.

I changed the default task priority from "Needs Triage" (90) to "Normal" (50) to make my flow simpler. I don't need someone else to set the initial priority.

Natural and By-priority sorting BOTH maintain their specific orders. Fucking weird. NEVER USE NATURAL. Ever. You have to set sort by priority and save as default for new boards.

Wikipedia is done with Phabricator and is a great resource, for example their project management guidelines.

I updated at the beginning of 2018 and Epriestley has added an action to move items to different "columns" through the UI. This was a major missing piece before on mobile, as drag-and-drop is not supported there.

Configure

User Management

Spammers start registering as soon as the site goes live. I have disabled registrations via email:

bin/auth unlock
Site > Auth > Username/Password provider > Edit > [ ] Register new accounts (uncheck it and save)
bin/auth lock

If a friend wants to register:

reverse the above steps, to enable registration
The user can now join on their own, with email verification (now that STMP is configured)
Site > People > approve the new user there
repeat the above steps to re-dis-able registration, whew...

Dashboard

The home screen is a dashboard. To add panels for a project:

go to the project workboard column you want in a panel feed
click the gear, "view as query"
change the limit to 3, and in the upper right, select Use Results > Add to dashboard

You only get two columns (cmon priestley ffs) so make good use of them.

Misc

You can customize the site banner now through the ui - yay thanks epriestley!

Navigate via Config > Core settings > User interface.

Install

Installing Phabricator is as simple as any other LAMP installation. We grabbed the three primary git repos, here:

m@bitpost cd development/phabricator
git clone https://github.com/phacility/libphutil.git
git clone https://github.com/phacility/arcanist.git
git clone https://github.com/phacility/phabricator.git

Then set up an alias and directory in apache. Then a mysql user + db. Browse to the url to finish. Easy peasy. Read on for further updates over time.

After putting up haproxy as the front end, I needed to add a "preamble" script to confirm we were actually using https through haproxy:

🌵 m@bitpost  [~/development/phabricator/phabricator/support] ls preamble.php 
lrwxrwxrwx 1 m m 78 Feb 17 15:03 preamble.php -> /home/m/development/config/bitpost/home/m/development/phabricator/preamble.php

Over time I migrated to a better git layout, using a [willcodeforcoffee] branch off master for my installation. Master can be updated at any time. I can rebase my branch to it on occasion. The only change so far has been:

libphutil/.arcconfig
arcanist/.arcconfig
phabricator/.arcconfig
phabricator/support/preamble.php (only in my repo)

Note that I have a COPY of these in my config repo:

 ls ~/development/config/bitpost/home/m/development/phabricator/
 -rw-r--r-- 1 m m   78 Aug  6  2016 .arcconfig
 -rw-r--r-- 1 m m   36 Feb 17 15:01 preamble.php
 -rw-r--r-- 1 m m  375 Apr 29  2016 readme.txt

Not ideal, but git hates symlinks so I can't connect the repos that way. Try to remember to keep the copy up to date on any change.

SMTP

SMTP was configured using a dedicated gmail account. It is delivered to m@bitpost.com. See private for details.

Check outgoing mail queue:

bin/mail list-outbound

API

The Phabricator API can be used to extract a query of tasks. You need to get a (permanent) auth certificate from arcanist:

m@bitpost cd development/phabricator/arcanist
bin/arc set-config default https://abettersoftware.org/
emacs .arcconfig # and set phabricator.uri to the same
emacs ../phabricator/.arcconfig # and set phabricator.uri to the same
bin/arc install-certificate

That will tell you to browse here. You'll get an "API Token" once you log in, eg cli-5sdfksomkhgvasdlfkwfelk or whatever (NOT that one).

Paste API Token from that page: cli-5fxsvztkshgvtc7ssdf
Writing ~/.arcrc...
SUCCESS!  API Token installed.

It then creates ~/.arcrc with the token, which is used by subsequent arc calls, like this:

Now you can use that in the API calls to authenticate, like this:

curl https://abettersoftware.org/api/maniphest.query -d api.token=cli-5fxsvztksdfsomkhgvczjtcdts

Pretty easy to use once you have the initial bullshit done. It certainly isn't secure to send over the wire though. The only viable solution is to use it server-side. See bitpost.com/ci.php code for details on using good old php to get the job done.

View active tokens here:

https://abettersoftware.org/settings/panel/apitokens/

Upgrade

ssh glam

Stop phabricator (possibly skip this step if you're brave/dumb?)

sudo service apache2 stop
cd development/phabricator/phabricator
bin/phd stop

Update code

cd ~/development/phabricator/phabricator
git branch # should be stable
git status # should have no changes (.arcconfig etc are in .gitignore so our config changes won't get in the way)
git pull
cd ../arcanist && git pull
cd ../libphutil && git pull

Upgrade the mysql schema

cd ~/development/phabricator
phabricator/bin/storage upgrade

Restart phabricator

sudo service apache start
cd development/phabricator
phabricator/bin/phd start

Troubleshooting

User accounts

Alternate ways to add users (other than self-registration via email verification):

go to https://willcodeforcoffee.org and add a user
don't worry about the password, you'll have to reset it
OR, to test, can we just validate the user? with this:

ssh bp
cd development/phabricator/phabricator
./bin/auth verify myemail@yo.com

OR, you can use the CLI to get a password reset link:

ssh bp
cd development/phabricator/phabricator
bin/auth recover myFabUser
# use or share the provided link to set a new password for the user

Old notes

Notes on failed attempt to change url

WARNING! No matter what I did, I couldn't get arcanist (or curl) to accept a subdomain's (agile.bitpost.com) CA certs. Browsers were fine. Shrug. Using a full domain worked fine. Maybe I'll revisit some time, but for now it's too much pain, move on.

Stop and reconfigure apache, restart
NOTE: currently we are using a 5-domain cert that includes bitpost.com, agile., www., ssl., mail.
Update phabricator config - this is different than and in addition to .arcconfig files!

phabricator/ $ ./bin/config set phabricator.base-uri 'https://agile.bitpost.com/'

Update ~/development/config/bitpost/home/m/development/phabricator/.arcconfig
And make sure that the three phab folders (phabricator, arcanist, libphutil) point to it
You MAY need to run through some of the API steps again, below

Alternatives

If phabricator becomes heavy to maintain or lacking in features, consider these:

@@ Line 1: / Line 1: @@
+== DEAD ==
+I put a lot of effort into this old girl.... and then she up and left me... (Epriestly could only give so much of himself...)  Kill it and move on to [[GitLab]]...
+NOTE I moved the GLAM 106- apache file from sites-enabled to sites-available.  Hopefully that is enough to put it to bed.
+== OLD ==
+Phabricator is a solid agile project manager and issue tracker, with a customizable workflow.
+=== My Workflow ===
 {| class="mw-collapsible wikitable"
 ! colspan="2" | WORKFLOW
@@ Line 5: / Line 17: @@
 | style="width: 12%;"| Workflow columns
 | style="width: 35%;"| ''Backlog'' => ''In Progress''
-| <span style="font-size:88%; line-height: 1.0em;">There is a third column ''Fixed'' that can be shown, it's nice to move '''Resolved''' items there on occasion to clean up the board.</span>
+| <span style="font-size:88%; line-height: 0.8em;">There is a third column ''Fixed'' that can be shown, it's nice to move '''Resolved''' items there on occasion to clean up the board.</span>
 |-
 | Create a task
 | Click dropdown on ''Backlog'', select ''Create Task''.
-| <span style="font-size:88%; line-height: 1.0em;">Or you can click the large + in the top-right toolbar, select Create Task, and assign the correct Project in the tags box.</span>
+| <span style="font-size:88%; line-height: 0.8em;">Or you can click the large + in the top-right toolbar, select Create Task, and assign the correct Project in the tags box.</span>
 |-
 | Start a task
 | Drag it from ''Backlog'' to ''In Progress''.
-| <span style="font-size:88%; line-height: 1.0em;">Drop above an existing task so the priority will be automatically set.  If this is not possible, you need to manually change '''Priority''' to '''High''' so that the CI dashboard shows the task.</span>
+| <span style="font-size:88%; line-height: 0.8em;">Drop above an existing task so the priority will be automatically set.  If this is not possible, you need to manually change '''Priority''' to '''High''' so that the CI dashboard shows the task.</span>
 |-
 | Finish a task
 | Change '''Status''' to '''Resolved'''.
-| <span style="font-size:88%; line-height: 1.0em;">This will remove the task from the board if you are only showing '''Open''' statuses.  You can drag the task from ''In Progress'' to ''Fixed''; this has no real effect on the task, but will keep your board better organized.  This can be done in bulk, later.  NOTE that the CI dashboard doesn't show '''Resolved''' tasks.</span>
+| <span style="font-size:88%; line-height: 0.8em;">This will hide the task on the CI dashboard.  It will also immediately remove the task from the board if you are only showing '''Open''' statuses.  You can also drag the task from ''In Progress'' to ''Fixed''; this has no real effect on the task, but will keep your board better organized.</span>
 |}
-{| class="mw-collapsible mw-collapsed wikitable"
-! Tips
-|-
-| If you are viewing a board by priority, and drag, the dropped task will have its priority automatically adjusted to fit in drag zone.  This works great if you can drag a new item from ''Backlog'' to a spot '''above''' an existing ''In Progress'' item.
-I changed the [https://thedigitalage.org/config/edit/maniphest.default-priority/ default task priority] from "Needs Triage" (90) to "Normal" (50) to make my flow simpler.  I don't need someone else to set the initial priority.
+=== Tips ===
+If you are viewing a board by priority, and drag, the dropped task will have its priority automatically adjusted to fit in drag zone.  This works great if you can drag a new item from ''Backlog'' to a spot '''above''' an existing ''In Progress'' item.
+I changed the [https://willcodeforcoffee.org/config/edit/maniphest.default-priority/ default task priority] from "Needs Triage" (90) to "Normal" (50) to make my flow simpler.  I don't need someone else to set the initial priority.
 Natural and By-priority sorting BOTH maintain their specific orders.  Fucking weird.  NEVER USE NATURAL.  Ever.  You have to set sort by priority and save as default for new boards.
 Wikipedia is done with Phabricator and is a great resource, for example [https://www.mediawiki.org/wiki/Phabricator/Project_management their project management guidelines].
-|}
-{| class="mw-collapsible mw-collapsed wikitable"
+I updated at the beginning of 2018 and Epriestley has added an action to move items to different "columns" through the UI.  This was a major missing piece before on mobile, as drag-and-drop is not supported there.
-! Maintenance
-|-
+=== Configure ===
-|
-* Stop phabricator (I usually ignore this step)
+==== User Management ====
-* Update code
-  m@bitpost cd development/phabricator/libphutil && git pull
+Spammers start registering as soon as the site goes live.  I have disabled registrations via email:
-  m@bitpost cd ../arcanist && git pull
+  bin/auth unlock
-  m@bitpost cd ../phabricator && git pull
+  Site > Auth > Username/Password provider > Edit > [ ] Register new accounts (uncheck it and save)
-* Upgrade the mysql schema
+  bin/auth lock
-  m@bitpost cd development/phabricator/phabricator
- bin/storage upgrade
+If a friend wants to register:
-* Restart phabricator
+* reverse the above steps, to enable registration
- # restart apache
+* The user can now join on their own, with email verification (now that STMP is configured)
- m@bitpost cd development/phabricator/phabricator
+* Site > People > approve the new user there
-  bin/phd start
+* repeat the above steps to re-dis-able registration, whew...
-|}
-{| class="mw-collapsible mw-collapsed wikitable"
+==== Dashboard ====
-! Install
-|-
+The home screen is a dashboard.  To add panels for a project:
-| Installing Phabricator is as simple as any other LAMP installation.  We grabbed the three primary git repos, here:
+* go to the project workboard column you want in a panel feed
+* click the gear, "view as query"
+* change the limit to 3, and in the upper right, select Use Results > Add to dashboard
+You only get two columns (cmon priestley ffs) so make good use of them.
+==== Misc ====
+You can [https://willcodeforcoffee.org/config/group/ui/ customize the site banner] now through the ui -  yay thanks epriestley!
+  Navigate via Config > Core settings > User interface.
+=== Install ===
+Installing Phabricator is as simple as any other LAMP installation.  We grabbed the three primary git repos, here:
   m@bitpost cd development/phabricator
   git clone https://github.com/phacility/libphutil.git
   git clone https://github.com/phacility/arcanist.git
   git clone https://github.com/phacility/phabricator.git
-Then set up an alias and directory in apache.  Then a mysql user + db.  Browse to the url to finish.  Easy peasy.
-|}
+Then set up an alias and directory in apache.  Then a mysql user + db.  Browse to the url to finish.  Easy peasy.  Read on for further updates over time.
-{| class="mw-collapsible mw-collapsed wikitable"
-! API
+After putting up haproxy as the front end, I needed to [https://secure.phabricator.com/book/phabricator/article/configuring_preamble/ add a "preamble" script] to confirm we were actually using https through haproxy:
-|-
+ 🌵 m@bitpost  [~/development/phabricator/phabricator/support] ls preamble.php
-| The [https://thedigitalage.org/conduit/method/maniphest.query/ Phabricator API] can be used to extract a query of tasks.  You need to get a (permanent) auth certificate from '''arcanist''':
+ lrwxrwxrwx 1 m m 78 Feb 17 15:03 preamble.php -> /home/m/development/config/bitpost/home/m/development/phabricator/preamble.php
+Over time I migrated to a better git layout, using a [willcodeforcoffee] branch off master for my installation.  Master can be updated at any time.  I can rebase my branch to it on occasion.  The only change so far has been:
+ libphutil/.arcconfig
+ arcanist/.arcconfig
+ phabricator/.arcconfig
+ phabricator/support/preamble.php (only in my repo)
+Note that I have a COPY of these in my config repo:
+  ls ~/development/config/bitpost/home/m/development/phabricator/
+  -rw-r--r-- 1 m m   78 Aug  6  2016 .arcconfig
+  -rw-r--r-- 1 m m   36 Feb 17 15:01 preamble.php
+  -rw-r--r-- 1 m m  375 Apr 29  2016 readme.txt
+Not ideal, but git hates symlinks so I can't connect the repos that way.  Try to remember to keep the copy up to date on any change.
+==== SMTP ====
+SMTP was configured using a dedicated gmail account.  It is delivered to m@bitpost.com.  See private for details.
+Check outgoing mail queue:
+ bin/mail list-outbound
+==== API ====
+The [https://thedigitalage.org/conduit/method/maniphest.query/ Phabricator API] can be used to extract a query of tasks.  You need to get a (permanent) auth certificate from '''arcanist''':
   m@bitpost cd development/phabricator/arcanist
-  bin/arc set-config default https://thedigitalage.org/
+  bin/arc set-config default https://abettersoftware.org/
   emacs .arcconfig # and set phabricator.uri to the same
+ emacs ../phabricator/.arcconfig # and set phabricator.uri to the same
   bin/arc install-certificate
-That will tell you to browse [https://thedigitalage.org/conduit/login/ here].
+That will tell you to browse [https://abettersoftware.org/conduit/login/ here].
 You'll get an "API Token" once you log in, eg cli-5sdfksomkhgvasdlfkwfelk or whatever (NOT that one).
   Paste API Token from that page: cli-5fxsvztkshgvtc7ssdf
@@ Line 74: / Line 127: @@
 Now you can use that in the API calls to authenticate, like this:
-  curl https://tdigitalage.org/api/maniphest.query -d api.token=cli-5fxsvztksdfsomkhgvczjtcdts
+  curl https://abettersoftware.org/api/maniphest.query -d api.token=cli-5fxsvztksdfsomkhgvczjtcdts
+Pretty easy to use once you have the initial bullshit done.  It certainly isn't secure to send over the wire though.
+The only viable solution is to use it server-side.  See bitpost.com/ci.php code for details on using good old php to get the job done.
+View active tokens here:
+ https://abettersoftware.org/settings/panel/apitokens/
+=== Upgrade ===
+ ssh glam
+* Stop phabricator (possibly skip this step if you're brave/dumb?)
+ sudo service apache2 stop
+ cd development/phabricator/phabricator
+ bin/phd stop
+* Update code
+ cd ~/development/phabricator/phabricator
+ git branch # should be stable
+ git status # should have no changes (.arcconfig etc are in .gitignore so our config changes won't get in the way)
+ git pull
+ cd ../arcanist && git pull
+ cd ../libphutil && git pull
+* Upgrade the mysql schema
+ cd ~/development/phabricator
+ phabricator/bin/storage upgrade
+* Restart phabricator
+ sudo service apache start
+ cd development/phabricator
+ phabricator/bin/phd start
+=== Troubleshooting ===
+==== User accounts ====
+Alternate ways to add users (other than self-registration via email verification):
+* go to https://willcodeforcoffee.org and add a user
+* don't worry about the password, you'll have to reset it
+* OR, to test, can we just validate the user?  with this:
+ ssh bp
+ cd development/phabricator/phabricator
+ ./bin/auth verify myemail@yo.com
+* OR, you can use the CLI to get a password reset link:
+ ssh bp
+ cd development/phabricator/phabricator
+ bin/auth recover myFabUser
+ # use or share the provided link to set a new password for the user
-Pretty easy to use once you have the initial bullshit done.  It certainly isn't secure though.
+==== Old notes ====
+* Notes on failed attempt to change url
-bitpost.com uses the API to get a list of tasks.  Generally, it's a really really bad setup though, as anyone can sniff out that auth token.  Use ssl, for sure: https://bitpost.com.  Maybe I should actually disable non-SSL bitpost.com...  Actually the only viable solution is to do it server-side.  Geesh.  See bitpost.com/ci.php code for details.
+WARNING!  No matter what I did, I couldn't get arcanist (or curl) to accept a subdomain's (agile.bitpost.com) CA certs.  Browsers were fine.  Shrug.  Using a full domain worked fine.  Maybe I'll revisit some time, but for now it's too much pain, move on.
+# Stop and reconfigure apache, restart
+# NOTE: currently we are using a 5-domain cert that includes bitpost.com, agile., www., ssl., mail.
+# Update phabricator config - this is different than and in addition to .arcconfig files!
+  phabricator/ $ ./bin/config set phabricator.base-uri 'https://agile.bitpost.com/'
+# Update ~/development/config/bitpost/home/m/development/phabricator/.arcconfig
+# And make sure that the three phab folders (phabricator, arcanist, libphutil) point to it
+# You MAY need to run through some of the API steps again, below
-View active tokens here:
+==== Alternatives ====
- https://thedigitalage.org/settings/panel/apitokens/
-|}
+If phabricator becomes heavy to maintain or lacking in features, consider these:
+* [https://taiga.io/ Taiga]
+* [https://wekan.github.io/ Wekan]
+* [https://opensource.com/alternatives/trello more...]