@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Managing Daemons with phd
2@group config
3
4Explains Phorge daemons and the daemon control program `phd`.
5
6= Overview =
7
8Phorge uses daemons (background processing scripts) to handle a number of
9tasks:
10
11 - tracking repositories, discovering new commits, and importing and parsing
12 commits;
13 - sending email; and
14 - collecting garbage, like old logs and caches.
15
16Daemons are started and stopped with **phd** (the **Ph**abricator **D**aemon
17launcher). Daemons can be monitored via a web console.
18
19You do not need to run daemons for most parts of Phorge to work, but some
20features (principally, repository tracking with Diffusion) require them and
21several features will benefit in performance or stability if you configure
22daemons.
23
24= phd =
25
26**phd** is a command-line script (located at `phorge/bin/phd`). To get
27a list of commands, run `phd help`:
28
29 phorge/ $ ./bin/phd help
30 NAME
31 phd - phorge daemon launcher
32 ...
33
34Generally, you will use:
35
36 - **phd start** to launch all daemons;
37 - **phd restart** to restart all daemons;
38 - **phd status** to get a list of running daemons; and
39 - **phd stop** to stop all daemons.
40
41If you want finer-grained control, you can use:
42
43 - **phd launch** to launch individual daemons; and
44 - **phd debug** to debug problems with daemons.
45
46NOTE: When you upgrade Phorge or change configuration, you should restart
47the daemons by running `phd restart`.
48
49Automatically start phd
50=======================
51
52NOTE: If you are opinionated against systemd, cover the eyes of your children
53right now!1!
54
55Computers are good in automatically starting stuff, thanks to the invention
56of the "init system".
57
58Phorge virtually supports any init system. Which one is yours? Don't worry.
59If you don't know, it's systemd.
60
61Phorge ships with a systemd configuration file, following some assumptions:
62
63 - Your lovely Phorge is installed `/somewhere/phorge`.
64 - Your repository storage location is `/somewhere/repositories`.
65 - You have a dedicated Unix user called `daemon-user` - coming from
66 @{article:Diffusion User Guide}.
67
68IMPORTANT: The instructions in this section should all be performed as
69super-user.
70
71First, link the phd service into your system configuration. This will ensure
72that when you update Phorge, the daemon service configuration is updated as
73well.
74
75```
76systemctl link /somewhere/phorge/resources/phd/phorge-phd.service
77```
78
79NOTE: If you're concerned about upgrades introducing unwanted changes, you may
80alternatively copy the unit file into `/etc/systemd/system`. If you do this,
81it's recommended to leave the unit unchanged and to follow the rest of the
82instructions as-is to help with merging in future updates manually.
83
84Create the following configuration so the service knows where Phorge is:
85
86```lang=ini,name=/etc/phorge/environment
87PHORGE_ROOT=/somewhere/phorge
88```
89
90Next, configure the service to use your daemon user, and give it access to your
91repository storage path. The following command will open up your default editor:
92
93```
94systemctl edit phorge-phd.service
95```
96
97In the editor, between the comments indicated in the file, place the following
98to set the user/group phd shall run as, along with the filesystem path(s) for
99Phorge's repository storage and the phd log location. The only paths you
100//must// include in `ReadWritePaths` are the paths in your phorge configuration
101that phd will //write// to:
102
103 - `repository.default-local-path`
104 - `phd.log-directory`
105 (Shown below as `/var/log/phorge/phd`; use the path you set in your config.)
106
107If have not explicitly set `phd.log-directory` the logs are placed in a
108temporary directory that is removed every time `phorge-phd.service` terminates
109and you do not need to configure `ReadWritePaths` for it. Even if you do not use
110the systemd service, the temporary directory phd uses by default may still be
111removed upon system reboot. If you care about being able to easily diagnose
112problems, set the option to ensure phd logs persist.
113
114```lang=ini,name=/etc/systemd/system/phorge-phd.service.d/override.conf
115[Service]
116User=daemon-user
117Group=daemon-user
118
119ReadWritePaths=/somewhere/repositories
120# uncomment or remove depending on phd.log-directory option.
121#ReadWritePaths=/var/log/phorge/phd
122```
123
124If your database service is managed by systemd and running on the same machine
125as Phorge (unlikely except in development environments), you may also wish to
126configure a dependency on it so that phd starts more reliably.
127
128Dependencies are configured by adding `Wants` and `After` systemd directives.
129Consult `man 5 systemd.unit` for the particulars of what those mean, but we'll
130add them with `systemctl edit phorge-phd.service` once again.
131
132**If you're using MariaDB:**
133
134Add the following to the top of the configuration you created above:
135
136```lang=ini,name=/etc/systemd/system/phorge-phd.service.d/override.conf
137[Unit]
138Wants=mariadb.service
139After=mariadb.service
140```
141
142The full file should look like the following when you're done:
143
144```lang=ini,name=/etc/systemd/system/phorge-phd.service.d/override.conf
145[Unit]
146Wants=mariadb.service
147After=mariadb.service
148
149[Service]
150User=daemon-user
151Group=daemon-user
152
153ReadWritePaths=/somewhere/repositories
154# uncomment or remove depending on phd.log-directory option.
155#ReadWritePaths=/var/log/phorge/phd
156```
157
158For other MySQL flavors, consult your system configuration for the appropriate
159unit name.
160
161To install this new systemd configuration, execute these commands as super-user:
162
163```
164systemctl enable --now phorge-phd
165```
166
167Now the process has started and will survive after any reboot.
168
169To check if everything is OK:
170
171```
172systemctl status phorge-phd
173```
174
175NOTE: In addition to the basic `phorge-phd.service` file, Phorge also ships with
176a systemd template unit in the same directory as the standard unit, for use with
177advanced or multi-tenant installations. The vast majority of installations will
178not need this unit.
179
180Anything else can be explored in depth by reading the systemd documentation.
181Applicable systemd man pages are `systemd.exec(5)` and `systemd.service(5)`,
182which can be scrutinized for details on how how to expand or restrict phd's
183system access beyond the reasonably restricted defaults.
184
185= Daemon Console =
186
187You can view status and debugging information for daemons in the Daemon Console
188via the web interface. Go to `/daemon/` in your install or navigate to
189{nav icon=home, name=Home > More Applications > Daemons }.
190
191
192The Daemon Console shows a list of all the daemons that have ever launched, and
193allows you to view log information for them. If you have issues with daemons,
194you may be able to find error information that will help you resolve the problem
195in the console.
196
197NOTE: The easiest way to figure out what's wrong with a daemon is usually to use
198**phd debug** to launch it instead of **phd start**. This will run it without
199daemonizing it, so you can see output in your console.
200
201= Available Daemons =
202
203You can get a list of launchable daemons with **phd list**:
204
205 - **test daemons** are not generally useful unless you are
206 developing daemon infrastructure or debugging a daemon problem;
207 - **PhabricatorTaskmasterDaemon** performs work from a task queue;
208 - **PhabricatorRepositoryPullLocalDaemon** daemons track repositories, for
209 more information see @{article:Diffusion User Guide}; and
210 - **PhabricatorTriggerDaemon** schedules event triggers (see
211 @{article:Understanding Event Triggers}) and cleans up old logs and caches.
212
213= Debugging and Tuning =
214
215In most cases, **phd start** handles launching all the daemons you need.
216However, you may want to use more granular daemon controls to debug daemons,
217launch custom daemons, or launch special daemons like the IRC bot.
218
219To debug a daemon, use `phd debug`:
220
221 phorge/bin/ $ ./phd debug <daemon>
222
223You can pass arguments like this (normal arguments are passed to the daemon
224control mechanism, not to the daemon itself):
225
226 phorge/bin/ $ ./phd debug <daemon> -- --flavor apple
227
228In debug mode, daemons do not daemonize, and they print additional debugging
229output to the console. This should make it easier to debug problems. You can
230terminate the daemon with `^C`.
231
232To launch a nonstandard daemon, use `phd launch`:
233
234 phorge/bin/ $ ./phd launch <daemon>
235
236This daemon will daemonize and run normally.
237
238== General Tips ==
239
240 - You can set the maximum number of taskmasters that will run at once
241 by adjusting `phd.taskmasters`. If you have a task backlog, try increasing
242 it.
243 - When you `phd launch` or `phd debug` a daemon, you can type any unique
244 substring of its name, so `phd launch pull` will work correctly.
245 - `phd stop` and `phd restart` stop **all** of the daemons on the machine, not
246 just those started with `phd start`. If you're writing a restart script,
247 have it launch any custom daemons explicitly after `phd restart`.
248 - You can write your own daemons and manage them with `phd` by extending
249 @{class:PhabricatorDaemon}. See @{article@contrib:Adding New Classes}.
250 - See @{article:Diffusion User Guide} for details about tuning the repository
251 daemon.
252
253
254Multiple Hosts
255==============
256
257For information about running daemons on multiple hosts, see
258@{article:Cluster: Daemons}.
259
260
261Next Steps
262==========
263
264Continue by:
265
266 - learning about the repository daemon with @{article:Diffusion User Guide};
267 or
268 - writing your own daemons with @{article@contrib:Adding New Classes}.