author | wenzelm |
Thu, 19 Dec 2019 16:55:33 +0100 | |
changeset 71323 | 7c27a379190f |
parent 71322 | 0256ce61f405 |
child 71329 | 2217c731d228 |
permissions | -rw-r--r-- |
71099 | 1 |
(*:maxLineLen=78:*) |
2 |
||
3 |
theory Phabricator |
|
4 |
imports Base |
|
5 |
begin |
|
6 |
||
71322 | 7 |
chapter \<open>Phabricator server setup \label{ch:phabricator}\<close> |
71099 | 8 |
|
9 |
text \<open> |
|
10 |
Phabricator\<^footnote>\<open>\<^url>\<open>https://www.phacility.com/phabricator\<close>\<close> is an open-source |
|
11 |
product to support the development process of complex software projects |
|
12 |
(open or closed ones). The official slogan is: |
|
13 |
||
14 |
\begin{quote} |
|
15 |
Discuss. Plan. Code. Review. Test. \\ |
|
16 |
Every application your project needs, all in one tool. |
|
17 |
\end{quote} |
|
18 |
||
19 |
Ongoing changes and discussions about changes are maintained uniformly |
|
20 |
within a MySQL database. There are standard connections to major version |
|
21 |
control systems: \<^bold>\<open>Subversion\<close>, \<^bold>\<open>Mercurial\<close>, \<^bold>\<open>Git\<close>. So Phabricator offers |
|
22 |
a counter-model to trends of monoculture and centralized version control, |
|
23 |
especially due to Microsoft's Github and Atlassian's Bitbucket. |
|
24 |
||
25 |
The small company behind Phabricator provides paid plans for support and |
|
71131 | 26 |
hosting of servers, but it is easy to do \<^emph>\<open>independent self-hosting\<close> on a |
27 |
standard LAMP server (Linux, Apache, MySQL, PHP). This merely requires a |
|
28 |
virtual machine on the Net, which can be rented cheaply from local hosting |
|
29 |
providers --- there is no need to follow big cloud corporations. So it is |
|
30 |
feasible to remain the master of your virtual home, following the slogan |
|
31 |
``own all your data''. In many respects, Phabricator is similar to the |
|
32 |
well-known Nextcloud\<^footnote>\<open>\<^url>\<open>https://nextcloud.org\<close>\<close> product, concerning both |
|
33 |
the technology and sociology. |
|
71099 | 34 |
|
35 |
\<^medskip> |
|
36 |
The following Phabricator instances may serve as examples: |
|
37 |
||
38 |
\<^item> Phabricator development \<^url>\<open>https://secure.phabricator.com\<close> |
|
39 |
\<^item> Wikimedia development \<^url>\<open>https://phabricator.wikimedia.org\<close> |
|
71290 | 40 |
\<^item> Blender development \<^url>\<open>https://developer.blender.org\<close> |
71099 | 41 |
\<^item> Mercurial development \<^url>\<open>https://phab.mercurial-scm.org\<close> |
42 |
\<^item> Isabelle development \<^url>\<open>https://isabelle-dev.sketis.net\<close> |
|
43 |
||
71296 | 44 |
\<^medskip> |
45 |
Initial Phabricator configuration requires many details to be done right. |
|
46 |
Isabelle provides some command-line tools to help with the setup, and |
|
47 |
afterwards Isabelle support is optional: it is possible to run and maintain |
|
48 |
the server, without requiring the somewhat bulky Isabelle distribution |
|
49 |
again. |
|
71322 | 50 |
|
51 |
\<^medskip> |
|
52 |
Assuming an existing Phabricator installation, the command-line tool @{tool |
|
53 |
hg_setup} (\secref{sec:hg-setup}) helps to create new repositories or to |
|
54 |
migrate old ones. In particular, this avoids the lengthy sequence of clicks |
|
55 |
in Phabricator to make a new private repository with hosting on the server. |
|
56 |
(Phabricator is a software project management platform, where initial |
|
57 |
repository setup happens rarely in practice.) |
|
71099 | 58 |
\<close> |
59 |
||
60 |
||
61 |
section \<open>Quick start\<close> |
|
62 |
||
63 |
text \<open> |
|
71131 | 64 |
The starting point is a fresh installation of \<^bold>\<open>Ubuntu 18.04 |
65 |
LTS\<close>\<^footnote>\<open>\<^url>\<open>https://ubuntu.com/download\<close>\<close>: this version is mandatory due to |
|
66 |
subtle dependencies on system packages and configuration that is assumed by |
|
67 |
the Isabelle setup tool. |
|
71099 | 68 |
|
69 |
For production use, a proper \<^emph>\<open>Virtual Server\<close> or \<^emph>\<open>Root Server\<close> product |
|
70 |
from a hosting provider will be required, including an Internet Domain Name |
|
71290 | 71 |
(\secref{sec:phabricator-domain}). |
71099 | 72 |
|
73 |
Initial experimentation also works on a local host, e.g.\ via |
|
71131 | 74 |
VirtualBox\<^footnote>\<open>\<^url>\<open>https://www.virtualbox.org\<close>\<close>. The public domain \<^verbatim>\<open>lvh.me\<close> is |
71290 | 75 |
used by default: it maps arbitrary subdomains to \<^verbatim>\<open>localhost\<close>. |
71099 | 76 |
|
77 |
All administrative commands need to be run as \<^verbatim>\<open>root\<close> user (e.g.\ via |
|
71131 | 78 |
\<^verbatim>\<open>sudo\<close>). Note that Isabelle refers to user-specific configuration in the |
79 |
user home directory via @{setting ISABELLE_HOME_USER} |
|
80 |
(\secref{sec:settings}); that may be different or absent for the root user |
|
81 |
and thus cause confusion. |
|
71099 | 82 |
\<close> |
83 |
||
84 |
||
85 |
subsection \<open>Initial setup\<close> |
|
86 |
||
87 |
text \<open> |
|
71131 | 88 |
Isabelle can manage multiple named Phabricator installations: this allows to |
89 |
separate administrative responsibilities, e.g.\ different approaches to user |
|
90 |
management for different projects. Subsequently we always use the default |
|
71290 | 91 |
name ``\<^verbatim>\<open>vcs\<close>'': the name will appear in file and directory locations, |
92 |
internal database names and URLs. |
|
71099 | 93 |
|
71131 | 94 |
The initial setup works as follows (with full Linux package upgrade): |
71099 | 95 |
|
71280
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
96 |
@{verbatim [display] \<open> isabelle phabricator_setup -U -M:\<close>} |
71099 | 97 |
|
71131 | 98 |
After installing many packages, cloning the Phabricator distribution, |
99 |
initializing the MySQL database and Apache, the tool prints an URL for |
|
71290 | 100 |
further configuration. Now the following needs to be provided by the web |
101 |
interface. |
|
71099 | 102 |
|
71131 | 103 |
\<^item> An initial user that will get administrator rights. There is no need to |
104 |
create a special \<^verbatim>\<open>admin\<close> account. Instead, a regular user that will take |
|
105 |
over this responsibility can be used here. Subsequently we assume that |
|
106 |
user \<^verbatim>\<open>makarius\<close> becomes the initial administrator. |
|
71099 | 107 |
|
108 |
\<^item> An \<^emph>\<open>Auth Provider\<close> to manage user names and passwords. None is provided |
|
109 |
by default, and Phabricator points out this omission prominently in its |
|
110 |
overview of \<^emph>\<open>Setup Issues\<close>: following these hints quickly leads to the |
|
111 |
place where a regular \<^emph>\<open>Username/Password\<close> provider can be added. |
|
112 |
||
71131 | 113 |
Alternatively, Phabricator can delegate the responsibility of |
114 |
authentication to big corporations like Google and Facebook, but these can |
|
71290 | 115 |
be easily ignored. Genuine self-hosting means to manage users directly, |
116 |
without outsourcing of authentication. |
|
71099 | 117 |
|
71131 | 118 |
\<^item> A proper password for the administrator can now be set, e.g.\ by the |
119 |
following command: |
|
71099 | 120 |
|
71131 | 121 |
@{verbatim [display] \<open> isabelle phabricator bin/auth recover makarius\<close>} |
71099 | 122 |
|
71131 | 123 |
The printed URL gives access to a login and password dialog in the web |
124 |
interface. |
|
71099 | 125 |
|
71131 | 126 |
Any further users will be able to provide a password directly, because the |
127 |
Auth Provider is already active. |
|
128 |
||
129 |
\<^item> The list of Phabricator \<^bold>\<open>Setup Issues\<close> should be studied with some |
|
71290 | 130 |
care, to make sure that no serious problems are remaining. For example, |
131 |
the request to lock the configuration can be fulfilled as follows: |
|
71099 | 132 |
|
71131 | 133 |
@{verbatim [display] \<open> isabelle phabricator bin/auth lock\<close>} |
71099 | 134 |
|
71131 | 135 |
\<^medskip> A few other Setup Issues might be relevant as well, e.g.\ the timezone |
136 |
of the server. Some more exotic points can be ignored: Phabricator |
|
71290 | 137 |
provides careful explanations about what it thinks could be wrong, while |
71131 | 138 |
leaving some room for interpretation. |
71099 | 139 |
\<close> |
140 |
||
141 |
||
142 |
subsection \<open>Mailer configuration\<close> |
|
143 |
||
144 |
text \<open> |
|
145 |
The next important thing is messaging: Phabricator needs to be able to |
|
71131 | 146 |
communicate with users on its own account, e.g.\ to reset passwords. The |
147 |
documentation has many variations on \<^emph>\<open>Configuring Outbound |
|
148 |
Email\<close>\<^footnote>\<open>\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/configuring_outbound_email\<close>\<close>, |
|
149 |
but a conventional SMTP server with a dedicated \<^verbatim>\<open>phabricator\<close> user is |
|
150 |
sufficient. There is no need to run a separate mail server on the |
|
151 |
self-hosted Linux machine: hosting providers often include such a service |
|
152 |
for free, e.g.\ as part of a web-hosting package. As a last resort it is |
|
153 |
also possible to use a corporate service like Gmail, but such dependency |
|
154 |
dilutes the whole effort of self-hosting. |
|
71099 | 155 |
|
156 |
\<^medskip> |
|
157 |
Mailer configuration requires a few command-line invocations as follows: |
|
158 |
||
159 |
@{verbatim [display] \<open> isabelle phabricator_setup_mail\<close>} |
|
160 |
||
71131 | 161 |
\<^noindent> This generates a JSON template file for the the mail account details. |
162 |
After editing that, the subsequent command will add and test it with |
|
163 |
Phabricator: |
|
71099 | 164 |
|
165 |
@{verbatim [display] \<open> isabelle phabricator_setup_mail -T makarius\<close>} |
|
166 |
||
71131 | 167 |
This tells Phabricator to send a message to the administrator created |
168 |
before; the output informs about success or errors. |
|
169 |
||
170 |
The mail configuration process can be refined and repeated until it works |
|
171 |
properly: host name, port number, protocol etc.\ all need to be correct. The |
|
172 |
\<^verbatim>\<open>key\<close> field in the JSON file identifies the name of the configuration that |
|
71099 | 173 |
will be overwritten each time, when taking over the parameters via |
174 |
\<^verbatim>\<open>isabelle phabricator_setup_mail\<close>. |
|
175 |
||
176 |
\<^medskip> |
|
71290 | 177 |
The effective mail configuration can be queried like this: |
71099 | 178 |
|
71103 | 179 |
@{verbatim [display] \<open> isabelle phabricator bin/config get cluster.mailers\<close>} |
180 |
\<close> |
|
181 |
||
182 |
||
71132 | 183 |
subsection \<open>SSH configuration\<close> |
184 |
||
185 |
text \<open> |
|
71323 | 186 |
SSH configuration is important to access hosted repositories with public-key |
187 |
authentication. It is done by a separate tool, because it affects the |
|
188 |
operating-system and all installations of Phabricator simultaneously. |
|
71132 | 189 |
|
71290 | 190 |
The subsequent configuration is convenient (and ambitious): it takes away |
191 |
the standard port 22 from the operating system and assigns it to |
|
192 |
Isabelle/Phabricator. |
|
71132 | 193 |
|
194 |
@{verbatim [display] \<open> isabelle phabricator_setup_ssh -p 22 -q 222\<close>} |
|
195 |
||
196 |
Afterwards, remote login to the server host needs to use that alternative |
|
71290 | 197 |
port 222. If there is a problem connecting again, the administrator can |
198 |
usually access a remote console via some web interface of the virtual server |
|
71267 | 199 |
provider. |
71132 | 200 |
|
201 |
\<^medskip> |
|
71267 | 202 |
The following alternative is more modest: it uses port 2222 for Phabricator, |
71290 | 203 |
and retains port 22 for the operating system. |
71132 | 204 |
|
205 |
@{verbatim [display] \<open> isabelle phabricator_setup_ssh -p 2222 -q 22\<close>} |
|
206 |
||
207 |
\<^medskip> |
|
208 |
The tool can be invoked multiple times with different parameters; ports are |
|
209 |
changed back and forth each time and services restarted. |
|
210 |
\<close> |
|
211 |
||
212 |
||
71290 | 213 |
subsection \<open>Public domain name and HTTPS configuration \label{sec:phabricator-domain}\<close> |
71278 | 214 |
|
215 |
text \<open> |
|
216 |
So far the Phabricator server has been accessible only on \<^verbatim>\<open>localhost\<close> (via |
|
217 |
the alias \<^verbatim>\<open>lvh.me\<close>). Proper configuration of a public Internet domain name |
|
218 |
(with HTTPS certificate from \<^emph>\<open>Let's Encrypt\<close>) works as follows. |
|
219 |
||
220 |
\<^item> Register a subdomain (e.g.\ \<^verbatim>\<open>vcs.example.org\<close>) as an alias for the IP |
|
221 |
address of the underlying Linux host. This usually works by some web |
|
222 |
interface of the hosting provider to edit DNS entries; it might require |
|
223 |
some time for updated DNS records to become publicly available. |
|
224 |
||
225 |
\<^item> Edit the Phabricator website configuration file in |
|
226 |
\<^path>\<open>/etc/apache2/sites-available/\<close> to specify \<^verbatim>\<open>ServerName\<close> and |
|
227 |
\<^verbatim>\<open>ServerAdmin\<close> like this: @{verbatim [display] \<open> ServerName vcs.example.org |
|
228 |
ServerAdmin webmaster@example.org\<close>} |
|
229 |
||
230 |
Then reload (or restart) Apache like this: |
|
231 |
@{verbatim [display] \<open> systemctl reload apache2\<close>} |
|
232 |
||
233 |
\<^item> Install \<^verbatim>\<open>certbot\<close> from \<^url>\<open>https://certbot.eff.org\<close> following the |
|
234 |
description for Apache and Ubuntu 18.04 on |
|
235 |
\<^url>\<open>https://certbot.eff.org/lets-encrypt/ubuntubionic-apache\<close>. Run |
|
236 |
\<^verbatim>\<open>certbot\<close> interactively and let it operate on the domain |
|
237 |
\<^verbatim>\<open>vcs.example.org\<close>. |
|
238 |
||
239 |
\<^item> Inform Phabricator about its new domain name like this: |
|
71290 | 240 |
@{verbatim [display] \<open> isabelle phabricator bin/config set \ |
71278 | 241 |
phabricator.base-uri https://vcs.example.org\<close>} |
242 |
||
71290 | 243 |
\<^item> Visit the website \<^verbatim>\<open>https://vcs.example.org\<close> and configure Phabricator |
244 |
as described before. The following options are particularly relevant for a |
|
245 |
public website: |
|
71278 | 246 |
|
247 |
\<^item> \<^emph>\<open>Auth Provider / Username/Password\<close>: disable \<^emph>\<open>Allow Registration\<close> to |
|
71290 | 248 |
avoid uncontrolled registrants; users can still be invited via email |
249 |
instead. |
|
71278 | 250 |
|
251 |
\<^item> Enable \<^verbatim>\<open>policy.allow-public\<close> to allow read-only access to resources, |
|
252 |
without requiring user registration. |
|
253 |
\<close> |
|
254 |
||
255 |
||
71296 | 256 |
section \<open>Global data storage and backups \label{sec:phabricator-backup}\<close> |
71271 | 257 |
|
258 |
text \<open> |
|
259 |
The global state of a Phabricator installation consists of two main parts: |
|
260 |
||
261 |
\<^enum> The \<^emph>\<open>root directory\<close> according to |
|
262 |
\<^path>\<open>/etc/isabelle-phabricator.conf\<close> or \<^verbatim>\<open>isabelle phabricator -l\<close>: it |
|
263 |
contains the main PHP program suite with administrative tools, and some |
|
264 |
configuration files. The default setup also puts hosted repositories here |
|
265 |
(subdirectory \<^verbatim>\<open>repo\<close>). |
|
266 |
||
267 |
\<^enum> Multiple \<^emph>\<open>MySQL databases\<close> with a common prefix derived from the |
|
268 |
installation name --- the same name is used as database user name. |
|
269 |
||
71290 | 270 |
The root user may invoke \<^verbatim>\<open>/usr/local/bin/isabelle-phabricator-dump\<close> |
71279 | 271 |
to create a complete database dump within the root directory. Afterwards it |
272 |
is sufficient to make a conventional \<^bold>\<open>file-system backup\<close> of everything. To |
|
71271 | 273 |
restore the database state, see the explanations on \<^verbatim>\<open>mysqldump\<close> in |
274 |
\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/configuring_backups\<close>. |
|
71279 | 275 |
|
276 |
\<^medskip> The following command-line tools are particularly interesting for advanced |
|
277 |
database maintenance (within the Phabricator root directory): |
|
278 |
@{verbatim [display] \<open> phabricator/bin/storage help dump |
|
279 |
phabricator/bin/storage help shell |
|
280 |
phabricator/bin/storage help destroy |
|
281 |
phabricator/bin/storage help renamespace\<close>} |
|
282 |
||
283 |
For example, copying a database snapshot from one installation to another |
|
284 |
works as follows. Run on the first installation root directory: |
|
285 |
||
286 |
@{verbatim [display] \<open> phabricator/bin/storage dump > dump1.sql |
|
71290 | 287 |
phabricator/bin/storage renamespace --from phabricator_vcs \ |
71279 | 288 |
--to phabricator_xyz --input dump1.sql --output dump2.sql\<close>} |
289 |
||
71290 | 290 |
Them run on the second installation root directory: |
71279 | 291 |
@{verbatim [display] \<open> phabricator/bin/storage destroy |
71290 | 292 |
phabricator/bin/storage shell < .../dump2.sql\<close>} |
71279 | 293 |
|
294 |
Local configuration in \<^verbatim>\<open>phabricator/config/local/\<close> and hosted repositories |
|
295 |
need to be treated separately within the file-system. For the latter |
|
296 |
see also these tools: |
|
297 |
@{verbatim [display] \<open> phabricator/bin/repository help list-paths |
|
298 |
phabricator/bin/repository help move-paths\<close>} |
|
71271 | 299 |
\<close> |
300 |
||
301 |
||
71286 | 302 |
section \<open>Upgrading Phabricator installations\<close> |
303 |
||
304 |
text \<open> |
|
305 |
The Phabricator developers publish a new version approx.\ every 1--4 weeks: |
|
306 |
see also \<^url>\<open>https://secure.phabricator.com/w/changelog\<close>. There is no need to |
|
307 |
follow such frequent updates on the spot, but it is a good idea to upgrade |
|
71296 | 308 |
occasionally --- after dump and/or backup (\secref{sec:phabricator-backup}). |
71286 | 309 |
|
310 |
The Isabelle/Phabricator setup provides a convenience tool to upgrade all |
|
311 |
installations uniformly: |
|
312 |
@{verbatim [display] \<open> /usr/local/bin/isabelle-phabricator-upgrade\<close>} |
|
313 |
||
314 |
This refers to the \<^verbatim>\<open>stable\<close> branch of the distribution repositories by |
|
315 |
default. Alternatively, it also possible to use the \<^verbatim>\<open>master\<close> like this: |
|
316 |
@{verbatim [display] \<open> /usr/local/bin/isabelle-phabricator-upgrade master\<close>} |
|
71296 | 317 |
|
318 |
\<^medskip> |
|
319 |
See |
|
320 |
\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/upgrading\<close> for |
|
321 |
further explanations on Phabricator upgrade. |
|
71286 | 322 |
\<close> |
323 |
||
324 |
||
71103 | 325 |
section \<open>Reference of command-line tools\<close> |
326 |
||
327 |
text \<open> |
|
328 |
The subsequent command-line tools usually require root user privileges on |
|
329 |
the underlying Linux system (e.g.\ via \<^verbatim>\<open>sudo bash\<close> to open a subshell, or |
|
71131 | 330 |
directly via \<^verbatim>\<open>sudo isabelle phabricator ...\<close>). |
71103 | 331 |
\<close> |
332 |
||
333 |
||
334 |
subsection \<open>\<^verbatim>\<open>isabelle phabricator\<close>\<close> |
|
335 |
||
336 |
text \<open> |
|
337 |
The @{tool_def phabricator} tool invokes a GNU bash command-line within the |
|
338 |
Phabricator home directory: |
|
339 |
@{verbatim [display] |
|
340 |
\<open>Usage: isabelle phabricator [OPTIONS] COMMAND [ARGS...] |
|
341 |
||
342 |
Options are: |
|
343 |
-l list available Phabricator installations |
|
344 |
-n NAME Phabricator installation name (default: "vcs") |
|
345 |
||
346 |
Invoke a command-line tool within the home directory of the named |
|
347 |
Phabricator installation.\<close>} |
|
348 |
||
349 |
Isabelle/Phabricator installations are registered in the global |
|
350 |
configuration file \<^path>\<open>/etc/isabelle-phabricator.conf\<close>, with name and |
|
351 |
root directory separated by colon (no extra whitespace). The home directory |
|
352 |
is the subdirectory \<^verbatim>\<open>phabricator\<close> within the root. |
|
353 |
||
354 |
\<^medskip> Option \<^verbatim>\<open>-l\<close> lists the available Phabricator installations with name and |
|
71276
b4401dfd6544
clarified "isabelle phabricator -l": avoid surprise with non-existent default installation;
wenzelm
parents:
71271
diff
changeset
|
355 |
root directory --- without invoking a command. |
71103 | 356 |
|
357 |
Option \<^verbatim>\<open>-n\<close> selects the explicitly named Phabricator installation. |
|
358 |
\<close> |
|
359 |
||
360 |
||
361 |
subsubsection \<open>Examples\<close> |
|
362 |
||
363 |
text \<open> |
|
364 |
Print the home directory of the Phabricator installation: |
|
71132 | 365 |
@{verbatim [display] \<open> isabelle phabricator pwd\<close>} |
71103 | 366 |
|
367 |
Print some Phabricator configuration information: |
|
71132 | 368 |
@{verbatim [display] \<open> isabelle phabricator bin/config get phabricator.base-uri\<close>} |
71103 | 369 |
|
370 |
The latter conforms to typical command templates seen in the original |
|
371 |
Phabricator documentation: |
|
71132 | 372 |
@{verbatim [display] \<open> phabricator/ $ ./bin/config get phabricator.base-uri\<close>} |
71103 | 373 |
|
374 |
Here the user is meant to navigate to the Phabricator home manually, in |
|
71131 | 375 |
contrast to \<^verbatim>\<open>isabelle phabricator\<close> doing it automatically thanks to the |
376 |
global configuration \<^path>\<open>/etc/isabelle-phabricator.conf\<close>. |
|
71103 | 377 |
\<close> |
378 |
||
379 |
||
380 |
subsection \<open>\<^verbatim>\<open>isabelle phabricator_setup\<close>\<close> |
|
381 |
||
382 |
text \<open> |
|
71290 | 383 |
The @{tool_def phabricator_setup} tool installs a fresh Phabricator instance |
384 |
on Ubuntu 18.04 LTS: |
|
71103 | 385 |
@{verbatim [display] \<open>Usage: isabelle phabricator_setup [OPTIONS] |
386 |
||
387 |
Options are: |
|
71280
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
388 |
-M SOURCE install Mercurial from source: local PATH, or URL, or ":" |
71103 | 389 |
-R DIR repository directory (default: "/var/www/phabricator-NAME/repo") |
390 |
-U full update of system packages before installation |
|
391 |
-n NAME Phabricator installation name (default: "vcs") |
|
392 |
-r DIR installation root directory (default: "/var/www/phabricator-NAME") |
|
393 |
||
394 |
Install Phabricator as LAMP application (Linux, Apache, MySQL, PHP). |
|
395 |
||
396 |
The installation name (default: "vcs") is mapped to a regular |
|
397 |
Unix user; this is relevant for public SSH access.\<close>} |
|
398 |
||
71131 | 399 |
Installation requires Linux root permissions. All required packages are |
71103 | 400 |
installed automatically beforehand, this includes the Apache web server and |
401 |
the MySQL database engine. |
|
402 |
||
71131 | 403 |
Global configuration in \<^verbatim>\<open>/etc\<close> or a few other directories like \<^verbatim>\<open>/var/www\<close> |
404 |
uses name prefixes like \<^verbatim>\<open>isabelle-phabricator\<close> or \<^verbatim>\<open>phabricator\<close>. Local |
|
71103 | 405 |
configuration for a particular installation uses more specific names derived |
71131 | 406 |
from \<^verbatim>\<open>phabricator-\<close>\<open>NAME\<close>, e.g.\ \<^verbatim>\<open>/var/www/phabricator-vcs\<close> for the |
407 |
default. |
|
71103 | 408 |
|
71131 | 409 |
Knowing the naming conventions, it is possible to purge a Linux installation |
410 |
from Isabelle/Phabricator with some effort, but there is no automated |
|
411 |
procedure for de-installation. In the worst case, it might be better to |
|
412 |
re-install the virtual machine from a clean image. |
|
71103 | 413 |
|
414 |
\<^medskip> |
|
415 |
Option \<^verbatim>\<open>-U\<close> ensures a full update of system packages, before installing |
|
71290 | 416 |
further packages required by Phabricator. This might require a reboot. |
71103 | 417 |
|
71280
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
418 |
Option \<^verbatim>\<open>-M:\<close> installs a standard Mercurial release from source: this works |
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
419 |
better than the package provided by Ubuntu 18.04. Alternatively, an explicit |
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
420 |
file path or URL the source archive (\<^verbatim>\<open>.tar.gz\<close>) may be here. This option is |
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
421 |
recommended for production use, but it requires to \<^emph>\<open>uninstall\<close> existing |
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
422 |
Mercurial packages provided by the operating system. |
5a2033fc8f3d
avoid odd (harmless) problem with Mercurial 4.5.3 provided by Ubuntu 18.04 on first push: "couldn't write revision branch cache names";
wenzelm
parents:
71279
diff
changeset
|
423 |
|
71103 | 424 |
Option \<^verbatim>\<open>-n\<close> provides an alternative installation name. The default name |
71131 | 425 |
\<^verbatim>\<open>vcs\<close> means ``version control system''. The name appears in the URL for SSH |
426 |
access, and thus has some relevance to end-users. The initial server URL |
|
427 |
also uses the same suffix, but that can (and should) be changed later via |
|
428 |
regular Apache configuration. |
|
71103 | 429 |
|
430 |
Option \<^verbatim>\<open>-r\<close> specifies an alternative installation root directory: it needs |
|
431 |
to be accessible for the Apache web server. |
|
432 |
||
433 |
Option \<^verbatim>\<open>-R\<close> specifies an alternative directory for repositories that are |
|
434 |
hosted by Phabricator. Provided that it is accessible for the Apache web |
|
71131 | 435 |
server, the directory can be reused for the \<^verbatim>\<open>hgweb\<close> view by Mercurial.\<^footnote>\<open>See |
436 |
also the documentation |
|
437 |
\<^url>\<open>https://www.mercurial-scm.org/wiki/PublishingRepositories\<close> and the |
|
438 |
example \<^url>\<open>https://isabelle.sketis.net/repos\<close>.\<close> |
|
71103 | 439 |
\<close> |
440 |
||
441 |
||
442 |
subsection \<open>\<^verbatim>\<open>isabelle phabricator_setup_mail\<close>\<close> |
|
443 |
||
444 |
text \<open> |
|
71290 | 445 |
The @{tool_def phabricator_setup_mail} tool provides mail configuration for |
446 |
an existing Phabricator installation: |
|
71103 | 447 |
@{verbatim [display] \<open>Usage: isabelle phabricator_setup_mail [OPTIONS] |
448 |
||
449 |
Options are: |
|
450 |
-T USER send test mail to Phabricator user |
|
451 |
-f FILE config file (default: "mailers.json" within |
|
452 |
Phabricator root) |
|
453 |
-n NAME Phabricator installation name (default: "vcs") |
|
454 |
||
455 |
Provide mail configuration for existing Phabricator installation.\<close>} |
|
456 |
||
457 |
Proper mail configuration is vital for Phabricator, but the details can be |
|
458 |
tricky. A common approach is to re-use an existing SMTP mail service, as is |
|
71131 | 459 |
often included in regular web hosting packages. It is sufficient to create |
460 |
one mail account for multiple Phabricator installations, but the |
|
461 |
configuration needs to be set for each installation. |
|
71103 | 462 |
|
463 |
The first invocation of \<^verbatim>\<open>isabelle phabricator_setup_mail\<close> without options |
|
464 |
creates a JSON template file. Its \<^verbatim>\<open>key\<close> entry should be changed to |
|
465 |
something sensible to identify the configuration, e.g.\ the Internet Domain |
|
71131 | 466 |
Name of the mail address. The \<^verbatim>\<open>options\<close> specify the SMTP server address and |
467 |
account information. |
|
71103 | 468 |
|
469 |
Another invocation of \<^verbatim>\<open>isabelle phabricator_setup_mail\<close> with updated JSON |
|
470 |
file will change the underlying Phabricator installation. This can be done |
|
471 |
repeatedly, until everything works as expected. |
|
472 |
||
473 |
Option \<^verbatim>\<open>-T\<close> invokes a standard Phabricator test procedure for the mail |
|
474 |
configuration. The argument needs to be a valid Phabricator user: the mail |
|
475 |
address is derived from the user profile. |
|
476 |
||
477 |
Option \<^verbatim>\<open>-f\<close> refers to an existing JSON configuration file, e.g.\ from a |
|
71131 | 478 |
previous successful Phabricator installation: sharing mailers setup with the |
479 |
same mail address is fine for outgoing mails; incoming mails are optional |
|
480 |
and not configured here. |
|
71099 | 481 |
\<close> |
482 |
||
71132 | 483 |
|
484 |
subsection \<open>\<^verbatim>\<open>isabelle phabricator_setup_ssh\<close>\<close> |
|
485 |
||
486 |
text \<open> |
|
71290 | 487 |
The @{tool_def phabricator_setup_ssh} tool configures a special SSH service |
71132 | 488 |
for all Phabricator installations: |
489 |
@{verbatim [display] \<open>Usage: isabelle phabricator_setup_ssh [OPTIONS] |
|
490 |
||
491 |
Options are: |
|
492 |
-p PORT sshd port for Phabricator servers (default: 2222) |
|
493 |
-q PORT sshd port for the operating system (default: 22) |
|
494 |
||
495 |
Configure ssh service for all Phabricator installations: a separate sshd |
|
496 |
is run in addition to the one of the operating system, and ports need to |
|
497 |
be distinct. |
|
498 |
||
499 |
A particular Phabricator installation is addressed by using its |
|
500 |
name as the ssh user; the actual Phabricator user is determined via |
|
501 |
stored ssh keys.\<close>} |
|
502 |
||
503 |
This is optional, but very useful. It allows to refer to hosted repositories |
|
504 |
via ssh with the usual public-key authentication. It also allows to |
|
505 |
communicate with a Phabricator server via the JSON API of |
|
506 |
\<^emph>\<open>Conduit\<close>\<^footnote>\<open>\<^url>\<open>https://secure.phabricator.com/book/phabricator/article/conduit\<close>\<close>. |
|
507 |
||
508 |
\<^medskip> The Phabricator SSH server distinguishes installations by their name, |
|
509 |
e.g.\ \<^verbatim>\<open>vcs\<close> as SSH user name. The public key that is used for |
|
510 |
authentication identifies the user within Phabricator: there is a web |
|
511 |
interface to provide that as part of the user profile. |
|
512 |
||
513 |
The operating system already has an SSH server (by default on port 22) that |
|
514 |
remains important for remote administration of the machine. |
|
515 |
||
516 |
\<^medskip> |
|
71292
8b745b4d71b5
more rebust setup for Subversion -- assuming that diffusion.ssh-port is only set in phabricator/conf/local/local.json, not in the database;
wenzelm
parents:
71290
diff
changeset
|
517 |
Options \<^verbatim>\<open>-p\<close> and \<^verbatim>\<open>-q\<close> allow to change the port assignment for both |
8b745b4d71b5
more rebust setup for Subversion -- assuming that diffusion.ssh-port is only set in phabricator/conf/local/local.json, not in the database;
wenzelm
parents:
71290
diff
changeset
|
518 |
servers. A common scheme is \<^verbatim>\<open>-p 22 -q 222\<close> to leave the standard port to |
71132 | 519 |
Phabricator, to simplify the ssh URL that users will see for remote |
71292
8b745b4d71b5
more rebust setup for Subversion -- assuming that diffusion.ssh-port is only set in phabricator/conf/local/local.json, not in the database;
wenzelm
parents:
71290
diff
changeset
|
520 |
repository clones.\<^footnote>\<open>For the rare case of hosting Subversion repositories, |
8b745b4d71b5
more rebust setup for Subversion -- assuming that diffusion.ssh-port is only set in phabricator/conf/local/local.json, not in the database;
wenzelm
parents:
71290
diff
changeset
|
521 |
port 22 is de-facto required. Otherwise Phabricator presents malformed |
8b745b4d71b5
more rebust setup for Subversion -- assuming that diffusion.ssh-port is only set in phabricator/conf/local/local.json, not in the database;
wenzelm
parents:
71290
diff
changeset
|
522 |
\<^verbatim>\<open>svn+ssh\<close> URLs with port specification.\<close> |
71132 | 523 |
|
524 |
Redirecting the operating system sshd to port 222 requires some care: it |
|
525 |
requires to adjust the remote login procedure, e.g.\ in \<^verbatim>\<open>$HOME/.ssh/config\<close> |
|
526 |
to add a \<^verbatim>\<open>Port\<close> specification for the server machine. |
|
527 |
\<close> |
|
528 |
||
71099 | 529 |
end |