@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
Add a little Drydock documentation
Summary: Ref T9252. Provide some general descriptions of Drydock in the docs.
Test Plan: Reading.
Reviewers: hach-que, chad
Reviewed By: chad
Maniphest Tasks: T9252
Differential Revision: https://secure.phabricator.com/D14215
+55
-3
+55
-3
src/docs/user/userguide/drydock.diviner
+55
-3
src/docs/user/userguide/drydock.diviner
···
1
1
@title Drydock User Guide
2
2
@group userguide
3
3
4
-
Configuring Drydock for machine resource management.
4
+
Drydock, a software and hardware resource manager.
5
+
6
+
Overview
7
+
========
8
+
9
+
WARNING: Drydock is very new and has many sharp edges. Prepare yourself for
10
+
a challenging adventure in unmapped territory, not a streamlined experience
11
+
where things work properly or make sense.
12
+
13
+
Drydock is an infrastructure application that primarily helps other
14
+
applications coordinate during complex build and deployment tasks. Typically,
15
+
you will configure Drydock to enable capabilities in other applications:
16
+
17
+
- Harbormaster can use Drydock to host builds.
18
+
- In the future, Differential will be able to use Drydock to perform
19
+
server-side merges.
20
+
21
+
Users will not normally interact with Drydock directly.
5
22
6
-
= Overview =
7
23
8
-
NOTE: Drydock is extremely new and not very useful yet.
24
+
What Drydock Does
25
+
=================
26
+
27
+
Drydock manages working copies, build hosts, and other software and hardware
28
+
resources that build and deployment processes may require in order to perform
29
+
useful work.
30
+
31
+
Many useful processes need a working copy of a repository (or some similar sort
32
+
of resource) so they can read files, perform version control operations, or
33
+
execute code.
34
+
35
+
For example, you might want to be able to automatically run unit tests, build a
36
+
binary, or generate documentation every time a new commit is pushed. Or you
37
+
might want to automatically merge a revision or cherry-pick a commit from a
38
+
development branch to a release branch. Any of these tasks need a working copy
39
+
of the repository before they can get underway.
40
+
41
+
These processes could just clone a new working copy when they started and
42
+
delete it when they finished. This works reasonably well at a small scale, but
43
+
will eventually hit limitations if you want to do things like: expand the build
44
+
tier to multiple machines; or automatically scale the tier up and down based on
45
+
usage; or reuse working copies to improve performance; or make sure things get
46
+
cleaned up after a process fails; or have jobs wait if the tier is too busy.
47
+
Solving these problems effectively requires coordination between the processes
48
+
doing the actual work.
49
+
50
+
Drydock solves these scaling problems by providing a central allocation
51
+
framework for //resources//, which are physical or virtual resources like a
52
+
build host or a working copy. Processes which need to share hardware or
53
+
software can use Drydock to coordinate creation, access, and destruction of
54
+
those resources.
55
+
56
+
Applications ask Drydock for resources matching a description, and it allocates
57
+
a corresponding resource by either finding a suitable unused resource or
58
+
creating a new resource. When work completes, the resource is returned to the
59
+
resource pool or destroyed.
60
+