--- a/src/Doc/System/Phabricator.thy Sat Jan 04 15:03:23 2025 +0100
+++ b/src/Doc/System/Phabricator.thy Sat Jan 04 15:09:47 2025 +0100
@@ -4,57 +4,53 @@
imports Base
begin
-chapter \<open>Phabricator server setup \label{ch:phabricator}\<close>
+chapter \<open>Phabricator / Phorge server setup \label{ch:phabricator}\<close>
text \<open>
- Phabricator\<^footnote>\<open>\<^url>\<open>https://www.phacility.com/phabricator\<close>\<close> is an open-source
- product to support the development process of complex software projects
- (open or closed ones). The official slogan is:
+ Phorge\<^footnote>\<open>\<^url>\<open>https://phorge.it\<close>\<close> is an open-source product to support the
+ development process of complex software projects (open or closed ones). It
+ is a community fork to replace the former
+ Phabricator\<^footnote>\<open>\<^url>\<open>https://www.phacility.com/phabricator\<close>\<close> project, which is
+ now inactive. Subsequently, the product name is always \<^emph>\<open>Phorge\<close> instead of
+ \<^emph>\<open>Phabricator\<close>, but files and other formal names usually refer to
+ \<^verbatim>\<open>phabricator\<close>.
+
+ Following the original tradition of Phabricator, almost everything in Phorge
+ is a bit different and unusual. The official project description is:
\begin{quote}
- Discuss. Plan. Code. Review. Test. \\
- Every application your project needs, all in one tool.
+ Your opinionated Free/Libre and Open Source, community driven platform
+ for collaborating, managing, organizing and reviewing software projects.
\end{quote}
Ongoing changes and discussions about changes are maintained uniformly
within a MySQL database. There are standard connections to major version
- control systems: \<^bold>\<open>Subversion\<close>, \<^bold>\<open>Mercurial\<close>, \<^bold>\<open>Git\<close>. So Phabricator offers
- a counter-model to trends of monoculture and centralized version control,
+ control systems: \<^bold>\<open>Subversion\<close>, \<^bold>\<open>Mercurial\<close>, \<^bold>\<open>Git\<close>. So Phorge offers a
+ counter-model to trends of monopoly and centralized version control,
especially due to Microsoft's Github and Atlassian's Bitbucket.
- The small company behind Phabricator provides paid plans for support and
- hosting of servers, but it is easy to do \<^emph>\<open>independent self-hosting\<close> on a
- standard LAMP server (Linux, Apache, MySQL, PHP). This merely requires a
- virtual machine on the Net, which can be rented cheaply from local hosting
- providers --- there is no need to follow big cloud corporations. So it is
- feasible to remain the master of your virtual home, following the slogan
- ``own all your data''. In many respects, Phabricator is similar to the
- well-known Nextcloud\<^footnote>\<open>\<^url>\<open>https://nextcloud.com\<close>\<close> product, concerning both
- the technology and sociology.
+ A notable public instance of Phorge is running on \<^url>\<open>https://gitpull.it\<close>.
+ Independent \<^emph>\<open>self-hosting\<close> requires an old-school LAMP server (Linux,
+ Apache, MySQL, PHP): a cheap virtual machine on the Net is sufficient, there
+ is no need for special ``cloud'' providers. So it is feasible to remain the
+ master of your virtual home, according to the principle ``to own all your
+ data''. Thus Phorge is similar to the well-known
+ Nextcloud\<^footnote>\<open>\<^url>\<open>https://nextcloud.com\<close>\<close> server product, concerning both the
+ technology and sociology.
\<^medskip>
- The following Phabricator instances may serve as examples:
-
- \<^item> Wikimedia development \<^url>\<open>https://phabricator.wikimedia.org\<close>
- \<^item> Mozilla development \<^url>\<open>https://phabricator.services.mozilla.com\<close>
- \<^item> Isabelle development \<^url>\<open>https://isabelle-dev.sketis.net\<close>
- \<^item> Phabricator development (mostly inactive after Jun-2021) \<^url>\<open>https://secure.phabricator.com\<close>
- \<^item> Phorge development (community fork and successor of Phabricator)
- \<^url>\<open>https://we.phorge.it\<close>
-
- \<^medskip>
- Initial Phabricator configuration requires many details to be done right.
+ Initial Phorge configuration requires many details to be done right.
Isabelle provides some command-line tools to help with the setup, and
afterwards Isabelle support is optional: it is possible to run and maintain
the server, without requiring the somewhat bulky Isabelle distribution
again.
\<^medskip>
- Assuming an existing Phabricator installation, the command-line tool @{tool
- hg_setup} (\secref{sec:hg-setup}) helps to create new repositories or to
- migrate old ones. In particular, this avoids the lengthy sequence of clicks
- in Phabricator to make a new private repository with hosting on the server.
- (Phabricator is a software project management platform, where initial
+ Assuming an existing installation of Phorge, the Isabelle command-line tool
+ @{tool hg_setup} (\secref{sec:hg-setup}) helps to create new repositories or
+ to migrate old ones. In particular, this avoids the lengthy sequence of
+ clicks in Phorge to make a new private repository with hosting on the
+ server. (Phorge is a software project management platform, where initial
repository setup happens rarely in practice.)
\<close>
@@ -62,19 +58,17 @@
section \<open>Quick start\<close>
text \<open>
- The starting point is a fresh installation of \<^bold>\<open>Ubuntu 20.04
- LTS\<close>\<^footnote>\<open>\<^url>\<open>https://ubuntu.com/download\<close>\<close>: this version is mandatory due to
+ The starting point is a fresh installation of \<^bold>\<open>Ubuntu 20.04 or 22.04
+ LTS\<close>\<^footnote>\<open>\<^url>\<open>https://ubuntu.com/download\<close>\<close>: these versions are mandatory due to
subtle dependencies on system packages and configuration that is assumed by
the Isabelle setup tool.
For production use, a proper \<^emph>\<open>Virtual Server\<close> or \<^emph>\<open>Root Server\<close> product
from a hosting provider will be required, including an Internet Domain Name
- (\secref{sec:phabricator-domain}).
-
- Initial experimentation also works on a local host, e.g.\ via
- VirtualBox\<^footnote>\<open>\<^url>\<open>https://www.virtualbox.org\<close>\<close>. The proforma domain
- \<^verbatim>\<open>localhost\<close> is used by default: it maps arbitrary subdomains to the usual
- \<^verbatim>\<open>localhost\<close> address. This allows to use e.g.
+ (\secref{sec:phorge-domain}). Initial experimentation also works on a local
+ host, e.g.\ via VirtualBox\<^footnote>\<open>\<^url>\<open>https://www.virtualbox.org\<close>\<close>. The proforma
+ domain \<^verbatim>\<open>localhost\<close> is used by default: it maps arbitrary subdomains to the
+ usual \<^verbatim>\<open>localhost\<close> address. This allows to use e.g.
\<^verbatim>\<open>http://phabricator-vcs.localhost\<close> for initial setup as described below.
All administrative commands need to be run as \<^verbatim>\<open>root\<close> user (e.g.\ via
@@ -88,7 +82,7 @@
subsection \<open>Initial setup\<close>
text \<open>
- Isabelle can manage multiple named Phabricator installations: this allows to
+ Isabelle can manage multiple named Phorge installations: this allows to
separate administrative responsibilities, e.g.\ different approaches to user
management for different projects. Subsequently we always use the default
name ``\<^verbatim>\<open>vcs\<close>'': the name will appear in file and directory locations,
@@ -98,7 +92,7 @@
@{verbatim [display] \<open> isabelle phabricator_setup -U -M:\<close>}
- After installing many packages, cloning the Phabricator distribution,
+ After installing many packages, cloning the Phorge distribution,
initializing the MySQL database and Apache, the tool prints an URL for
further configuration. Now the following needs to be provided by the web
interface.
@@ -109,11 +103,11 @@
user \<^verbatim>\<open>makarius\<close> becomes the initial administrator.
\<^item> An \<^emph>\<open>Auth Provider\<close> to manage user names and passwords. None is provided
- by default, and Phabricator points out this omission prominently in its
+ by default, and Phorge points out this omission prominently in its
overview of \<^emph>\<open>Setup Issues\<close>: following these hints quickly leads to the
place where a regular \<^emph>\<open>Username/Password\<close> provider can be added.
- Alternatively, Phabricator can delegate the responsibility of
+ Alternatively, Phorge can delegate the responsibility of
authentication to big corporations like Google and Facebook, but these can
be easily ignored. Genuine self-hosting means to manage users directly,
without outsourcing of authentication.
@@ -129,26 +123,26 @@
Any further users will be able to provide a password directly, because the
Auth Provider is already active.
- \<^item> The list of Phabricator \<^bold>\<open>Setup Issues\<close> should be studied with some
- care, to make sure that no serious problems are remaining. For example,
- the request to lock the configuration can be fulfilled as follows:
+ \<^item> The list of Phorge \<^bold>\<open>Setup Issues\<close> should be studied with some care, to
+ make sure that no serious problems are remaining. For example, the request
+ to lock the configuration can be fulfilled as follows:
@{verbatim [display] \<open> isabelle phabricator bin/auth lock\<close>}
\<^medskip> A few other Setup Issues might be relevant as well, e.g.\ the timezone
- of the server. Some more exotic points can be ignored: Phabricator
- provides careful explanations about what it thinks could be wrong, while
- leaving some room for interpretation.
+ of the server. Some more exotic points can be ignored: Phorge provides
+ careful explanations about what it thinks could be wrong, while leaving
+ some room for interpretation.
\<close>
subsection \<open>Mailer configuration\<close>
text \<open>
- The next important thing is messaging: Phabricator needs to be able to
+ The next important thing is messaging: Phorge needs to be able to
communicate with users on its own account, e.g.\ to reset passwords. The
documentation has many variations on \<^emph>\<open>Configuring Outbound
- Email\<close>\<^footnote>\<open>\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/configuring_outbound_email\<close>\<close>,
+ Email\<close>\<^footnote>\<open>\<^url>\<open>https://we.phorge.it/book/phorge/article/configuring_outbound_email\<close>\<close>,
but a conventional SMTP server with a dedicated \<^verbatim>\<open>phabricator\<close> user is
sufficient. There is no need to run a separate mail server on the
self-hosted Linux machine: hosting providers often include such a service
@@ -163,11 +157,11 @@
\<^noindent> This generates a JSON template file for the mail account details.
After editing that, the subsequent command will add and test it with
- Phabricator:
+ Phorge:
@{verbatim [display] \<open> isabelle phabricator_setup_mail -T makarius\<close>}
- This tells Phabricator to send a message to the administrator created
+ This tells Phorge to send a message to the administrator created
before; the output informs about success or errors.
The mail configuration process can be refined and repeated until it works
@@ -188,11 +182,11 @@
text \<open>
SSH configuration is important to access hosted repositories with public-key
authentication. It is done by a separate tool, because it affects the
- operating-system and all installations of Phabricator simultaneously.
+ operating-system and all installations of Phorge simultaneously.
The subsequent configuration is convenient (and ambitious): it takes away
the standard port 22 from the operating system and assigns it to
- Isabelle/Phabricator.
+ Isabelle/Phorge.
@{verbatim [display] \<open> isabelle phabricator_setup_ssh -p 22 -q 222\<close>}
@@ -202,8 +196,8 @@
provider.
\<^medskip>
- The following alternative is more modest: it uses port 2222 for Phabricator,
- and retains port 22 for the operating system.
+ The following alternative is more modest: it uses port 2222 for Phorge, and
+ retains port 22 for the operating system.
@{verbatim [display] \<open> isabelle phabricator_setup_ssh -p 2222 -q 22\<close>}
@@ -213,19 +207,19 @@
\<close>
-subsection \<open>Internet domain name and HTTPS configuration \label{sec:phabricator-domain}\<close>
+subsection \<open>Internet domain name and HTTPS configuration \label{sec:phorge-domain}\<close>
text \<open>
- So far the Phabricator server has been accessible only on \<^verbatim>\<open>localhost\<close>.
- Proper configuration of a public Internet domain name (with HTTPS
- certificate from \<^emph>\<open>Let's Encrypt\<close>) works as follows.
+ So far the Phorge server has been accessible only on \<^verbatim>\<open>localhost\<close>. Proper
+ configuration of a public Internet domain name (with HTTPS certificate from
+ \<^emph>\<open>Let's Encrypt\<close>) works as follows.
\<^item> Register a subdomain (e.g.\ \<^verbatim>\<open>vcs.example.org\<close>) as an alias for the IP
address of the underlying Linux host. This usually works by some web
interface of the hosting provider to edit DNS entries; it might require
some time for updated DNS records to become publicly available.
- \<^item> Edit the Phabricator website configuration file in
+ \<^item> Edit the Phorge website configuration file in
\<^path>\<open>/etc/apache2/sites-available/\<close> to specify \<^verbatim>\<open>ServerName\<close> and
\<^verbatim>\<open>ServerAdmin\<close> like this: @{verbatim [display] \<open> ServerName vcs.example.org
ServerAdmin webmaster@example.org\<close>}
@@ -234,16 +228,14 @@
@{verbatim [display] \<open> systemctl reload apache2\<close>}
\<^item> Install \<^verbatim>\<open>certbot\<close> from \<^url>\<open>https://certbot.eff.org\<close> following the
- description for Apache and Ubuntu 20 on
- \<^url>\<open>https://certbot.eff.org/instructions?ws=apache&os=ubuntufocal\<close>. Run
- \<^verbatim>\<open>certbot\<close> interactively and let it operate on the domain
- \<^verbatim>\<open>vcs.example.org\<close>.
+ description for Apache and Ubuntu Linux. Run \<^verbatim>\<open>certbot\<close> interactively and
+ let it operate on the domain \<^verbatim>\<open>vcs.example.org\<close>.
- \<^item> Inform Phabricator about its new domain name like this:
+ \<^item> Inform Phorge about its new domain name like this:
@{verbatim [display] \<open> isabelle phabricator bin/config set \
phabricator.base-uri https://vcs.example.org\<close>}
- \<^item> Visit the website \<^verbatim>\<open>https://vcs.example.org\<close> and configure Phabricator
+ \<^item> Visit the website \<^verbatim>\<open>https://vcs.example.org\<close> and configure Phorge
as described before. The following options are particularly relevant for a
public website:
@@ -256,14 +248,14 @@
\<^item> Adjust \<^verbatim>\<open>phabricator.cookie-prefix\<close> for multiple installations with
overlapping domains (see also the documentation of this configuration
- option within Phabricator).
+ option within Phorge).
\<close>
-section \<open>Global data storage and backups \label{sec:phabricator-backup}\<close>
+section \<open>Global data storage and backups \label{sec:phorge-backup}\<close>
text \<open>
- The global state of a Phabricator installation consists of two main parts:
+ The global state of a Phorge installation consists of two main parts:
\<^enum> The \<^emph>\<open>root directory\<close> according to
\<^path>\<open>/etc/isabelle-phabricator.conf\<close> or \<^verbatim>\<open>isabelle phabricator -l\<close>: it
@@ -278,12 +270,13 @@
create a complete database dump within the root directory. Afterwards it is
sufficient to make a conventional \<^bold>\<open>file-system backup\<close> of everything. To
restore the database state, see the explanations on \<^verbatim>\<open>mysqldump\<close> in
- \<^url>\<open>https://secure.phabricator.com/book/phabricator/article/configuring_backups\<close>;
- some background information is in
- \<^url>\<open>https://secure.phabricator.com/book/phabflavor/article/so_many_databases\<close>.
+ \<^url>\<open>https://we.phorge.it/book/phorge/article/configuring_backups\<close>; some
+ background information is in
+ \<^url>\<open>https://we.phorge.it/book/flavor/article/so_many_databases\<close>.
\<^medskip> The following command-line tools are particularly interesting for advanced
- database maintenance (within the Phabricator root directory):
+ database maintenance (within the Phorge root directory that is traditionally
+ called \<^verbatim>\<open>phabricator\<close>):
@{verbatim [display] \<open> phabricator/bin/storage help dump
phabricator/bin/storage help shell
phabricator/bin/storage help destroy
@@ -308,16 +301,16 @@
\<close>
-section \<open>Upgrading Phabricator installations\<close>
+section \<open>Upgrading Phorge installations\<close>
text \<open>
- The Phabricator developers publish a new version approx.\ every 1--4 weeks:
- see also \<^url>\<open>https://secure.phabricator.com/w/changelog\<close>. There is no need to
- follow such frequent updates on the spot, but it is a good idea to upgrade
- occasionally --- with the usual care to avoid breaking a production system
- (see also \secref{sec:phabricator-backup} for database dump and backup).
+ The Phorge community publishes a new stable version several times per year:
+ see also \<^url>\<open>https://we.phorge.it/w/changelog\<close>. There is no need to follow
+ updates on the spot, but it is a good idea to upgrade occasionally --- with
+ the usual care to avoid breaking a production system (see also
+ \secref{sec:phorge-backup} for database dump and backup).
- The Isabelle/Phabricator setup provides a convenience tool to upgrade all
+ The Isabelle/Phorge setup provides a convenience tool to upgrade all
installations uniformly:
@{verbatim [display] \<open> /usr/local/bin/isabelle-phabricator-upgrade\<close>}
@@ -326,9 +319,8 @@
@{verbatim [display] \<open> /usr/local/bin/isabelle-phabricator-upgrade master\<close>}
\<^medskip>
- See
- \<^url>\<open>https://secure.phabricator.com/book/phabricator/article/upgrading\<close> for
- further explanations on Phabricator upgrade.
+ See \<^url>\<open>https://we.phorge.it/book/phorge/article/upgrading\<close> for further
+ explanations on Phorge upgrade.
\<close>
@@ -345,43 +337,43 @@
text \<open>
The @{tool_def phabricator} tool invokes a GNU bash command-line within the
- Phabricator home directory:
+ Phorge home directory:
@{verbatim [display]
\<open>Usage: isabelle phabricator [OPTIONS] COMMAND [ARGS...]
Options are:
- -l list available Phabricator installations
- -n NAME Phabricator installation name (default: "vcs")
+ -l list available Phorge installations
+ -n NAME Phorge installation name (default: "vcs")
Invoke a command-line tool within the home directory of the named
- Phabricator installation.\<close>}
+ Phorge installation.\<close>}
- Isabelle/Phabricator installations are registered in the global
- configuration file \<^path>\<open>/etc/isabelle-phabricator.conf\<close>, with name and
- root directory separated by colon (no extra whitespace). The home directory
- is the subdirectory \<^verbatim>\<open>phabricator\<close> within the root.
+ Isabelle/Phorge installations are registered in the global configuration
+ file \<^path>\<open>/etc/isabelle-phabricator.conf\<close>, with name and root directory
+ separated by colon (no extra whitespace). The home directory is the
+ subdirectory \<^verbatim>\<open>phabricator\<close> within the root.
- \<^medskip> Option \<^verbatim>\<open>-l\<close> lists the available Phabricator installations with name and
- root directory --- without invoking a command.
+ \<^medskip> Option \<^verbatim>\<open>-l\<close> lists the available Phorge installations with name and root
+ directory --- without invoking a command.
- Option \<^verbatim>\<open>-n\<close> selects the explicitly named Phabricator installation.
+ Option \<^verbatim>\<open>-n\<close> selects the explicitly named Phorge installation.
\<close>
subsubsection \<open>Examples\<close>
text \<open>
- Print the home directory of the Phabricator installation:
+ Print the home directory of the Phorge installation:
@{verbatim [display] \<open> isabelle phabricator pwd\<close>}
- Print some Phabricator configuration information:
+ Print some Phorge configuration information:
@{verbatim [display] \<open> isabelle phabricator bin/config get phabricator.base-uri\<close>}
The latter conforms to typical command templates seen in the original
- Phabricator documentation:
+ Phorge documentation:
@{verbatim [display] \<open> phabricator/ $ ./bin/config get phabricator.base-uri\<close>}
- Here the user is meant to navigate to the Phabricator home manually, in
+ Here the user is meant to navigate to the Phorge home manually, in
contrast to \<^verbatim>\<open>isabelle phabricator\<close> doing it automatically thanks to the
global configuration \<^path>\<open>/etc/isabelle-phabricator.conf\<close>.
\<close>
@@ -390,7 +382,7 @@
subsection \<open>\<^verbatim>\<open>isabelle phabricator_setup\<close>\<close>
text \<open>
- The @{tool_def phabricator_setup} tool installs a fresh Phabricator instance
+ The @{tool_def phabricator_setup} tool installs a fresh Phorge instance
on Ubuntu 20.04 or 22.04 LTS:
@{verbatim [display] \<open>Usage: isabelle phabricator_setup [OPTIONS]
@@ -398,11 +390,11 @@
-M SOURCE install Mercurial from source: local PATH, or URL, or ":"
-R DIR repository directory (default: "/var/www/phabricator-NAME/repo")
-U full update of system packages before installation
- -n NAME Phabricator installation name (default: "vcs")
+ -n NAME Phorge installation name (default: "vcs")
-o OPTION override Isabelle system OPTION (via NAME=VAL or NAME)
-r DIR installation root directory (default: "/var/www/phabricator-NAME")
- Install Phabricator as LAMP application (Linux, Apache, MySQL, PHP).
+ Install Phorge as LAMP application (Linux, Apache, MySQL, PHP).
The installation name (default: "vcs") is mapped to a regular
Unix user; this is relevant for public SSH access.\<close>}
@@ -418,21 +410,19 @@
default.
Knowing the naming conventions, it is possible to purge a Linux installation
- from Isabelle/Phabricator with some effort, but there is no automated
+ from Isabelle/Phorge with some effort, but there is no automated
procedure for de-installation. In the worst case, it might be better to
re-install the virtual machine from a clean image.
\<^medskip>
Option \<^verbatim>\<open>-U\<close> ensures a full update of system packages, before installing
- further packages required by Phabricator. This might require a reboot.
+ further packages required by Phorge. This might require a reboot.
- Option \<^verbatim>\<open>-M:\<close> installs a standard Mercurial release from source --- the one
- that is used by the Phabricator hosting service
- \<^url>\<open>https://admin.phacility.com\<close>. This avoids various problems with the
- package provided by Ubuntu 20.04. Alternatively, an explicit file path or
- URL the source archive (\<^verbatim>\<open>.tar.gz\<close>) may be given here. This option is
- recommended for production use, but it requires to \<^emph>\<open>uninstall\<close> existing
- Mercurial packages provided by the operating system.
+ Option \<^verbatim>\<open>-M:\<close> installs a standard Mercurial release from source: a specific
+ version that is known to work on Ubuntu 20.04 or 22.04, respectively. It is
+ also possible to specify the path or URL of the source archive (\<^verbatim>\<open>.tar.gz\<close>).
+ This option is recommended for production use, but it requires to
+ \<^emph>\<open>uninstall\<close> existing Mercurial packages provided by the operating system.
Option \<^verbatim>\<open>-n\<close> provides an alternative installation name. The default name
\<^verbatim>\<open>vcs\<close> means ``version control system''. The name appears in the URL for SSH
@@ -441,14 +431,14 @@
regular Apache configuration.
Option \<^verbatim>\<open>-o\<close> augments the environment of Isabelle system options: relevant
- options for Isabelle/Phabricator have the prefix ``\<^verbatim>\<open>phabricator_\<close>'' (see
+ options for Isabelle/Phorge have the prefix ``\<^verbatim>\<open>phabricator_\<close>'' (see
also the result of e.g. ``\<^verbatim>\<open>isabelle options -l\<close>'').
Option \<^verbatim>\<open>-r\<close> specifies an alternative installation root directory: it needs
to be accessible for the Apache web server.
Option \<^verbatim>\<open>-R\<close> specifies an alternative directory for repositories that are
- hosted by Phabricator. Provided that it is accessible for the Apache web
+ hosted by Phorge. Provided that it is accessible for the Apache web
server, the directory can be reused for the \<^verbatim>\<open>hgweb\<close> view by Mercurial.\<^footnote>\<open>See
also the documentation
\<^url>\<open>https://www.mercurial-scm.org/wiki/PublishingRepositories\<close> and the
@@ -460,21 +450,20 @@
text \<open>
The @{tool_def phabricator_setup_mail} tool provides mail configuration for
- an existing Phabricator installation:
+ an existing Phorge installation:
@{verbatim [display] \<open>Usage: isabelle phabricator_setup_mail [OPTIONS]
Options are:
- -T USER send test mail to Phabricator user
- -f FILE config file (default: "mailers.json" within
- Phabricator root)
- -n NAME Phabricator installation name (default: "vcs")
+ -T USER send test mail to Phorge user
+ -f FILE config file (default: "mailers.json" within Phorge root)
+ -n NAME Phorge installation name (default: "vcs")
- Provide mail configuration for existing Phabricator installation.\<close>}
+ Provide mail configuration for existing Phorge installation.\<close>}
- Proper mail configuration is vital for Phabricator, but the details can be
+ Proper mail configuration is vital for Phorge, but the details can be
tricky. A common approach is to re-use an existing SMTP mail service, as is
often included in regular web hosting packages. It is sufficient to create
- one mail account for multiple Phabricator installations, but the
+ one mail account for multiple Phorge installations, but the
configuration needs to be set for each installation.
The first invocation of \<^verbatim>\<open>isabelle phabricator_setup_mail\<close> without options
@@ -484,15 +473,15 @@
account information.
Another invocation of \<^verbatim>\<open>isabelle phabricator_setup_mail\<close> with updated JSON
- file will change the underlying Phabricator installation. This can be done
+ file will change the underlying Phorge installation. This can be done
repeatedly, until everything works as expected.
- Option \<^verbatim>\<open>-T\<close> invokes a standard Phabricator test procedure for the mail
- configuration. The argument needs to be a valid Phabricator user: the mail
+ Option \<^verbatim>\<open>-T\<close> invokes a standard Phorge test procedure for the mail
+ configuration. The argument needs to be a valid Phorge user: the mail
address is derived from the user profile.
Option \<^verbatim>\<open>-f\<close> refers to an existing JSON configuration file, e.g.\ from a
- previous successful Phabricator installation: sharing mailers setup with the
+ previous successful Phorge installation: sharing mailers setup with the
same mail address is fine for outgoing mails; incoming mails are optional
and not configured here.
\<close>
@@ -502,29 +491,29 @@
text \<open>
The @{tool_def phabricator_setup_ssh} tool configures a special SSH service
- for all Phabricator installations:
+ for all Phorge installations:
@{verbatim [display] \<open>Usage: isabelle phabricator_setup_ssh [OPTIONS]
Options are:
- -p PORT sshd port for Phabricator servers (default: 2222)
+ -p PORT sshd port for Phorge servers (default: 2222)
-q PORT sshd port for the operating system (default: 22)
- Configure ssh service for all Phabricator installations: a separate sshd
+ Configure ssh service for all Phorge installations: a separate sshd
is run in addition to the one of the operating system, and ports need to
be distinct.
- A particular Phabricator installation is addressed by using its
- name as the ssh user; the actual Phabricator user is determined via
+ A particular Phorge installation is addressed by using its
+ name as the ssh user; the actual Phorge user is determined via
stored ssh keys.\<close>}
This is optional, but very useful. It allows to refer to hosted repositories
via ssh with the usual public-key authentication. It also allows to
- communicate with a Phabricator server via the JSON API of
- \<^emph>\<open>Conduit\<close>\<^footnote>\<open>\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/conduit\<close>\<close>.
+ communicate with a Phorge server via the JSON API of
+ \<^emph>\<open>Conduit\<close>\<^footnote>\<open>\<^url>\<open>https://we.phorge.it/book/phorge/article/conduit\<close>\<close>.
- \<^medskip> The Phabricator SSH server distinguishes installations by their name,
+ \<^medskip> The Phorge SSH server distinguishes installations by their name,
e.g.\ \<^verbatim>\<open>vcs\<close> as SSH user name. The public key that is used for
- authentication identifies the user within Phabricator: there is a web
+ authentication identifies the user within Phorge: there is a web
interface to provide that as part of the user profile.
The operating system already has an SSH server (by default on port 22) that
@@ -533,10 +522,10 @@
\<^medskip>
Options \<^verbatim>\<open>-p\<close> and \<^verbatim>\<open>-q\<close> allow to change the port assignment for both
servers. A common scheme is \<^verbatim>\<open>-p 22 -q 222\<close> to leave the standard port to
- Phabricator, to simplify the ssh URL that users will see for remote
- repository clones.\<^footnote>\<open>For the rare case of hosting Subversion repositories,
- port 22 is de-facto required. Otherwise Phabricator presents malformed
- \<^verbatim>\<open>svn+ssh\<close> URLs with port specification.\<close>
+ Phorge, to simplify the ssh URL that users will see for remote repository
+ clones.\<^footnote>\<open>For the rare case of hosting Subversion repositories, port 22 is
+ de-facto required. Otherwise Phorge presents malformed \<^verbatim>\<open>svn+ssh\<close> URLs with
+ port specification.\<close>
Redirecting the operating system sshd to port 222 requires some care: it
requires to adjust the remote login procedure, e.g.\ in \<^verbatim>\<open>$HOME/.ssh/config\<close>
--- a/src/Pure/Tools/phabricator.scala Sat Jan 04 15:03:23 2025 +0100
+++ b/src/Pure/Tools/phabricator.scala Sat Jan 04 15:09:47 2025 +0100
@@ -1,11 +1,11 @@
/* Title: Pure/Tools/phabricator.scala
Author: Makarius
-Support for Phabricator server, notably for Ubuntu 20.04 or 22.04 LTS.
+Support for Phorge / Phabricator server, notably for Ubuntu 20.04 or 22.04 LTS.
See also:
- - https://www.phacility.com/phabricator
- - https://secure.phabricator.com/book/phabricator
+ - https://phorge.it
+ - https://we.phorge.it/book/phorge
*/
package isabelle
@@ -262,7 +262,7 @@
def get_config(name: String): Config =
read_config().find(config => config.name == name) getOrElse
- error("Bad Isabelle/Phabricator installation " + quote(name))
+ error("Bad Isabelle/Phorge installation " + quote(name))
@@ -271,7 +271,7 @@
/* Isabelle tool wrapper */
val isabelle_tool1 =
- Isabelle_Tool("phabricator", "invoke command-line tool within Phabricator home directory",
+ Isabelle_Tool("phabricator", "invoke command-line tool within Phorge home directory",
Scala_Project.here,
{ args =>
var list = false
@@ -281,11 +281,11 @@
Usage: isabelle phabricator [OPTIONS] COMMAND [ARGS...]
Options are:
- -l list available Phabricator installations
- -n NAME Phabricator installation name (default: """ + quote(default_name) + """)
+ -l list available Phorge installations
+ -n NAME Phorge installation name (default: """ + quote(default_name) + """)
Invoke a command-line tool within the home directory of the named
- Phabricator installation.
+ Phorge installation.
""",
"l" -> (_ => list = true),
"n:" -> (arg => name = arg))
@@ -317,7 +317,7 @@
}
else if (Linux.user_description(name) != description) {
error("User " + quote(name) + " already exists --" +
- " for Phabricator it should have the description:\n " + quote(description))
+ " for Phorge it should have the description:\n " + quote(description))
}
}
@@ -392,13 +392,13 @@
error("Bad installation name: " + quote(name))
}
- user_setup(daemon_user, "Phabricator Daemon User", ssh_setup = true)
- user_setup(name, "Phabricator SSH User")
+ user_setup(daemon_user, "Phorge Daemon User", ssh_setup = true)
+ user_setup(name, "Phorge SSH User")
/* basic installation */
- progress.echo("\nPhabricator installation ...")
+ progress.echo("\nPhorge installation ...")
val root_path = if (root.nonEmpty) Path.explode(root) else default_root(name)
val repo_path = if (repo.nonEmpty) Path.explode(repo) else default_repo(name)
@@ -406,7 +406,7 @@
val configs = read_config()
for (config <- configs if config.name == name) {
- error("Duplicate Phabricator installation " + quote(name) + " in " + config.root)
+ error("Duplicate Phorge installation " + quote(name) + " in " + config.root)
}
if (!Isabelle_System.bash("mkdir -p " + File.bash_path(root_path)).ok) {
@@ -522,7 +522,7 @@
echo " $(ls -hs "$ROOT/database/dump.sql.gz" | cut -d" " -f1)" """)
- /* Phabricator upgrade */
+ /* Phorge upgrade */
command_setup(isabelle_phabricator_name(name = "upgrade"),
init =
@@ -592,7 +592,7 @@
try {
Linux.service_install(phd_name,
"""[Unit]
-Description=PHP daemon manager for Isabelle/Phabricator
+Description=PHP daemon manager for Isabelle/Phorge
After=syslog.target network.target """ + webserver.system_name + """.service mysql.service
[Service]
@@ -619,7 +619,7 @@
/* Isabelle tool wrapper */
val isabelle_tool2 =
- Isabelle_Tool("phabricator_setup", "setup Phabricator server on Ubuntu Linux",
+ Isabelle_Tool("phabricator_setup", "setup Phorge server on Ubuntu Linux",
Scala_Project.here,
{ args =>
var mercurial_source = ""
@@ -638,14 +638,14 @@
""" + standard_mercurial_source + """
-R DIR repository directory (default: """ + default_repo("NAME") + """)
-U full update of system packages before installation
- -n NAME Phabricator installation name (default: """ + quote(default_name) + """)
+ -n NAME Phorge installation name (default: """ + quote(default_name) + """)
-o OPTION override Isabelle system OPTION (via NAME=VAL or NAME)
-r DIR installation root directory (default: """ + default_root("NAME") + """)
-w NAME webserver name (""" +
all_webservers.map(w => quote(w.user_name)).mkString (" or ") +
", default: " + quote(default_webserver.user_name) + """)
- Install Phabricator as Linux service, based on webserver + PHP + MySQL.
+ Install Phorge as Linux service, based on webserver + PHP + MySQL.
The installation name (default: """ + quote(default_name) + """) is mapped to a regular
Unix user; this is relevant for public SSH access.
@@ -707,7 +707,7 @@
if (test_user.nonEmpty) {
progress.echo("Sending test mail to " + quote(test_user))
progress.bash(cwd = config.home, echo = true,
- script = """echo "Test from Phabricator ($(date))" | bin/mail send-test --subject "Test" --to """ +
+ script = """echo "Test from Phorge ($(date))" | bin/mail send-test --subject "Test" --to """ +
Bash.string(test_user)).check
}
}
@@ -730,7 +730,7 @@
/* Isabelle tool wrapper */
val isabelle_tool3 =
- Isabelle_Tool("phabricator_setup_mail", "setup mail for one Phabricator installation",
+ Isabelle_Tool("phabricator_setup_mail", "setup mail for one Phorge installation",
Scala_Project.here,
{ args =>
var test_user = ""
@@ -741,11 +741,11 @@
Usage: isabelle phabricator_setup_mail [OPTIONS]
Options are:
- -T USER send test mail to Phabricator user
- -f FILE config file (default: """ + default_mailers + """ within Phabricator root)
- -n NAME Phabricator installation name (default: """ + quote(default_name) + """)
+ -T USER send test mail to Phorge user
+ -f FILE config file (default: """ + default_mailers + """ within Phorge root)
+ -n NAME Phorge installation name (default: """ + quote(default_name) + """)
- Provide mail configuration for existing Phabricator installation.
+ Provide mail configuration for existing Phorge installation.
""",
"T:" -> (arg => test_user = arg),
"f:" -> (arg => config_file = Some(Path.explode(arg))),
@@ -812,7 +812,7 @@
val configs = read_config()
if (server_port == system_port) {
- error("Port for Phabricator sshd coincides with system port: " + system_port)
+ error("Port for Phorge sshd coincides with system port: " + system_port)
}
val sshd_conf_system = Path.explode("/etc/ssh/sshd_config")
@@ -838,7 +838,7 @@
fi""", exit = "exit 1")
File.write(sshd_conf_server,
-"""# OpenBSD Secure Shell server for Isabelle/Phabricator
+"""# OpenBSD Secure Shell server for Isabelle/Phorge
AuthorizedKeysCommand """ + ssh_command.implode + """
AuthorizedKeysCommandUser """ + daemon_user + """
AuthorizedKeysFile none
@@ -857,7 +857,7 @@
Linux.service_install(ssh_name,
"""[Unit]
-Description=OpenBSD Secure Shell server for Isabelle/Phabricator
+Description=OpenBSD Secure Shell server for Isabelle/Phorge
After=network.target auditd.service isabelle-phabricator-phd.service
ConditionPathExists=!/etc/ssh/sshd_not_to_be_run
@@ -890,7 +890,7 @@
/* Isabelle tool wrapper */
val isabelle_tool4 =
- Isabelle_Tool("phabricator_setup_ssh", "setup ssh service for all Phabricator installations",
+ Isabelle_Tool("phabricator_setup_ssh", "setup ssh service for all Phorge installations",
Scala_Project.here,
{ args =>
var server_port = default_server_port
@@ -900,15 +900,15 @@
Usage: isabelle phabricator_setup_ssh [OPTIONS]
Options are:
- -p PORT sshd port for Phabricator servers (default: """ + default_server_port + """)
+ -p PORT sshd port for Phorge servers (default: """ + default_server_port + """)
-q PORT sshd port for the operating system (default: """ + default_system_port + """)
- Configure ssh service for all Phabricator installations: a separate sshd
+ Configure ssh service for all Phorge installations: a separate sshd
is run in addition to the one of the operating system, and ports need to
be distinct.
- A particular Phabricator installation is addressed by using its
- name as the ssh user; the actual Phabricator user is determined via
+ A particular Phorge installation is addressed by using its
+ name as the ssh user; the actual Phorge user is determined via
stored ssh keys.
""",
"p:" -> (arg => server_port = Value.Int.parse(arg)),