@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
phd: improve setup documentation
Summary:
Address some concerns raised on D26181 after it landed.
- Running mysql on the same host: provide guidance on adding a dependency on mariadb.
- Linking directly: clarify that users can copy the unit, but now with `cp` instead of `ctrl+c`.
- User/group need changing: provide instructions on configuring the unit with systemd "drop-ins".
Test Plan:
- Check over the prose to make sure it's not too confusing.
- Confirm that the commands given to users do what they're supposed to do.
- Run `./bin/diviner generate` and view the results to ensure they're visually pleasing.
Reviewers: avivey, O1 Blessed Committers
Reviewed By: avivey, O1 Blessed Committers
Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno
Differential Revision: https://we.phorge.it/D26215
+109
-14
+95
-12
src/docs/user/configuration/managing_daemons.diviner
+95
-12
src/docs/user/configuration/managing_daemons.diviner
···
58
58
Phorge virtually supports any init system. Which one is yours? Don't worry.
59
59
If you don't know, it's systemd.
60
60
61
-
We propose a minimal systemd configuration file, following some assumptions:
61
+
Phorge ships with a systemd configuration file, following some assumptions:
62
62
63
-
- your lovely Phorge is installed `/somewhere`
64
-
- you have a database service called `mariadb`
65
-
- you have a dedicated Unix user called `daemon-user` - coming from
66
-
@{article:Diffusion User Guide}
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
67
68
-
With the above assumptions, link the phd service into your system configuration.
69
-
As super-user, run:
68
+
IMPORTANT: The instructions in this section should all be performed as
69
+
super-user.
70
+
71
+
First, link the phd service into your system configuration. This will ensure
72
+
that when you update Phorge, the daemon service configuration is updated as
73
+
well.
70
74
71
75
```
72
76
systemctl link /somewhere/phorge/resources/phd/phorge-phd.service
73
77
```
74
78
75
-
Then, also as super-user, create the following configuration:
79
+
NOTE: If you're concerned about upgrades introducing unwanted changes, you may
80
+
alternatively copy the unit file into `/etc/systemd/system`. If you do this,
81
+
it's recommended to leave the unit unchanged and to follow the rest of the
82
+
instructions as-is to help with merging in future updates manually.
83
+
84
+
Create the following configuration so the service knows where Phorge is:
76
85
77
86
```lang=ini,name=/etc/phorge/environment
78
87
PHORGE_ROOT=/somewhere/phorge
79
88
```
80
89
90
+
Next, configure the service to use your daemon user, and give it access to your
91
+
repository storage path. The following command will open up your default editor:
92
+
93
+
```
94
+
systemctl edit phorge-phd.service
95
+
```
96
+
97
+
In the editor, between the comments indicated in the file, place the following
98
+
to set the user/group phd shall run as, along with the filesystem path(s) for
99
+
Phorge's repository storage and the phd log location. The only paths you
100
+
//must// include in `ReadWritePaths` are the paths in your phorge configuration
101
+
that 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
+
107
+
If have not explicitly set `phd.log-directory` the logs are placed in a
108
+
temporary directory that is removed every time `phorge-phd.service` terminates
109
+
and you do not need to configure `ReadWritePaths` for it. Even if you do not use
110
+
the systemd service, the temporary directory phd uses by default may still be
111
+
removed upon system reboot. If you care about being able to easily diagnose
112
+
problems, set the option to ensure phd logs persist.
113
+
114
+
```lang=ini,name=/etc/systemd/system/phorge-phd.service.d/override.conf
115
+
[Service]
116
+
User=daemon-user
117
+
Group=daemon-user
118
+
119
+
ReadWritePaths=/somewhere/repositories
120
+
# uncomment or remove depending on phd.log-directory option.
121
+
#ReadWritePaths=/var/log/phorge/phd
122
+
```
123
+
124
+
If your database service is managed by systemd and running on the same machine
125
+
as Phorge (unlikely except in development environments), you may also wish to
126
+
configure a dependency on it so that phd starts more reliably.
127
+
128
+
Dependencies are configured by adding `Wants` and `After` systemd directives.
129
+
Consult `man 5 systemd.unit` for the particulars of what those mean, but we'll
130
+
add them with `systemctl edit phorge-phd.service` once again.
131
+
132
+
**If you're using MariaDB:**
133
+
134
+
Add 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]
138
+
Wants=mariadb.service
139
+
After=mariadb.service
140
+
```
141
+
142
+
The 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]
146
+
Wants=mariadb.service
147
+
After=mariadb.service
148
+
149
+
[Service]
150
+
User=daemon-user
151
+
Group=daemon-user
152
+
153
+
ReadWritePaths=/somewhere/repositories
154
+
# uncomment or remove depending on phd.log-directory option.
155
+
#ReadWritePaths=/var/log/phorge/phd
156
+
```
157
+
158
+
For other MySQL flavors, consult your system configuration for the appropriate
159
+
unit name.
160
+
81
161
To install this new systemd configuration, execute these commands as super-user:
82
162
83
163
```
···
92
172
systemctl status phorge-phd
93
173
```
94
174
95
-
NOTE: In addition to the basic `phd.service` file, Phorge also ships with a
96
-
systemd "template unit" in the same directory as the standard unit, for use with
97
-
advanced or multi-tenant installations. This is an advanced feature that the
98
-
majority of installations will not need.
175
+
NOTE: In addition to the basic `phorge-phd.service` file, Phorge also ships with
176
+
a systemd template unit in the same directory as the standard unit, for use with
177
+
advanced or multi-tenant installations. The vast majority of installations will
178
+
not need this unit.
99
179
100
180
Anything else can be explored in depth by reading the systemd documentation.
181
+
Applicable systemd man pages are `systemd.exec(5)` and `systemd.service(5)`,
182
+
which can be scrutinized for details on how how to expand or restrict phd's
183
+
system access beyond the reasonably restricted defaults.
101
184
102
185
= Daemon Console =
103
186
+9
-2
src/docs/user/upgrading.diviner
+9
-2
src/docs/user/upgrading.diviner
···
58
58
on every system:
59
59
60
60
- Stop the webserver (including `php-fpm`, if you use it).
61
-
- Stop the daemons, with `phorge/bin/phd stop`.
61
+
- Stop the daemons with `phorge/bin/phd stop` or `systemctl stop phorge-phd`.
62
62
- Run `git pull` in `arcanist/` and `phorge/`.
63
63
- Run `phorge/bin/storage upgrade`.
64
-
- Start the daemons, with `phorge/bin/phd start`.
64
+
- If using systemd, `systemctl daemon-reload`.
65
+
- Start the daemons, with `phorge/bin/phd start`
66
+
or `systemctl start phorge-phd`.
65
67
- Restart the webserver (and `php-fpm`, if you stopped it earlier).
66
68
67
69
For some more discussion details, see @{article:Configuration Guide}.
···
89
91
90
92
# Stop daemons.
91
93
$ROOT/phorge/bin/phd stop
94
+
# If using systemd to manage the daemons:
95
+
# systemctl stop phorge-phd
92
96
93
97
# If running the notification server, stop it.
94
98
# $ROOT/phorge/bin/aphlict stop
···
117
121
sudo /etc/init.d/httpd start
118
122
119
123
# Restart daemons.
124
+
# If using systemd, you may need to pick up changes to the phorge-phd unit:
125
+
# systemctl daemon-reload
126
+
# systemctl start phorge-phd
120
127
$ROOT/phorge/bin/phd start
121
128
122
129
# If running the notification server, start it.
+5
src/docs/user/userguide/diffusion_hosting.diviner
+5
src/docs/user/userguide/diffusion_hosting.diviner
···
63
63
If you do not plan to make repositories available over SSH, you do not need
64
64
to create or configure this user.
65
65
66
+
IMPORTANT: As a general service management philosophy, service users are
67
+
virtually always named after the service they are for. You are **strongly**
68
+
encouraged to pick something other than `daemon-user` for running the daemons. A
69
+
good username might be `phd`.
70
+
66
71
To create these users:
67
72
68
73
- Create a `www-user` if one does not already exist. In most cases, this