Skip to content

Commit 9726b48

Browse files
purpleideapurpleidea
committed
docs, readme: Improve new user experience
This hopefully improves some docs for new users, and makes releases more easily available.
1 parent fc6032d commit 9726b48

File tree

5 files changed

+243
-151
lines changed

5 files changed

+243
-151
lines changed

‎Makefile

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
# along with this program. If not, see <http://www.gnu.org/licenses/>.
1717

1818
SHELL = /usr/bin/env bash
19-
.PHONY: all art cleanart version program lang path deps run race bindata generate build build-debug crossbuild clean test gofmt yamlfmt format docs rpmbuild mkdirs rpm srpm spec tar upload upload-sources upload-srpms upload-rpms copr tag release funcgen
19+
.PHONY: all art cleanart version program lang path deps run race bindata generate build build-debug crossbuild clean test gofmt yamlfmt format docs rpmbuild mkdirs rpm srpm spec tar upload upload-sources upload-srpms upload-rpms upload-releases copr tag release funcgen
2020
.SILENT: clean bindata
2121

2222
# a large amount of output from this `find`, can cause `make` to be much slower!
@@ -326,6 +326,10 @@ upload-rpms: rpmbuild/RPMS/ rpmbuild/RPMS/SHA256SUMS rpmbuild/RPMS/SHA256SUMS.as
326326
rsync -avz --prune-empty-dirs rpmbuild/RPMS/ $(SERVER):$(REMOTE_PATH)/RPMS/; \
327327
fi
328328

329+
upload-releases:
330+
echo Running releases/ upload...
331+
rsync -avz --exclude '.mkdir' --exclude 'mgmt-release.url' releases/ $(SERVER):$(REMOTE_PATH)/releases/
332+
329333
#
330334
# copr build
331335
#

‎README.md

Lines changed: 54 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,56 @@
99
[![Patreon](https://img.shields.io/badge/patreon-donate-yellow.svg?style=flat-square)](https://www.patreon.com/purpleidea)
1010
[![Liberapay](https://img.shields.io/badge/liberapay-donate-yellow.svg?style=flat-square)](https://liberapay.com/purpleidea/donate)
1111

12+
## About:
13+
14+
`Mgmt` is a real-time automation tool. It is familiar to existing configuration
15+
management software, but is drastically more powerful as it can allow you to
16+
build real-time, closed-loop feedback systems, in a very safe way, and with a
17+
surprisingly small amout of our `mcl` code. For example, the following code will
18+
ensure that your file server is set to read-only when it's friday.
19+
20+
```mcl
21+
import "datetime"
22+
$is_friday = datetime.weekday(datetime.now()) == "friday"
23+
file "/srv/files/" {
24+
state => "exists",
25+
mode => if $is_friday { # this updates the mode, the instant it changes!
26+
"0550"
27+
} else {
28+
"0770"
29+
},
30+
}
31+
```
32+
33+
It can run continuously, intermittently, or on-demand, and in the first case, it
34+
will guarantee that your system is always in the desired state for that instant!
35+
In this mode it can run as a decentralized cluster of agents across your
36+
network, each exchanging information with the others in real-time, to respond to
37+
your changing needs. For example, if you want to ensure that some resource runs
38+
on a maximum of two hosts in your cluster, you can specify that as well:
39+
40+
```mcl
41+
import "sys"
42+
import "world"
43+
44+
# we'll set a few scheduling options:
45+
$opts = struct{strategy => "rr", max => 2, ttl => 10,}
46+
47+
# schedule in a particular namespace with options:
48+
$set = world.schedule("xsched", $opts)
49+
50+
if sys.hostname() in $set {
51+
# use your imagination to put something more complex right here...
52+
print "i got scheduled" {} # this will run on the chosen machines
53+
}
54+
```
55+
56+
As you add and remove hosts from the cluster, the real-time `schedule` function
57+
will dynamically pick up to two hosts from the available pool. These specific
58+
functions aren't intrinsic to the core design, and new ones can be easily added.
59+
60+
Please read on if you'd like to learn more...
61+
1262
## Community:
1363

1464
Come join us in the `mgmt` community!
@@ -30,15 +80,15 @@ approach. The project contains an engine and a language.
3080

3181
Mgmt is a fairly new project. It is usable today, but not yet feature complete.
3282
With your help you'll be able to influence our design and get us to 1.0 sooner!
33-
Interested developers should read the [quick start guide](docs/quick-start-guide.md).
83+
Interested users should read the [quick start guide](docs/quick-start-guide.md).
3484

3585
## Documentation:
3686

3787
Please read, enjoy and help improve our documentation!
3888

3989
| Documentation | Additional Notes |
4090
|---|---|
41-
| [quick start guide](docs/quick-start-guide.md) | for mgmt developers |
91+
| [quick start guide](docs/quick-start-guide.md) | for mgmt everyone |
4292
| [frequently asked questions](docs/faq.md) | for everyone |
4393
| [general documentation](docs/documentation.md) | for everyone |
4494
| [language guide](docs/language-guide.md) | for everyone |
@@ -61,18 +111,13 @@ question, and a patch with the answer!
61111

62112
Feel free to grab one of the straightforward [#mgmtlove](https://github.com/purpleidea/mgmt/labels/mgmtlove)
63113
issues if you're a first time contributor to the project or if you're unsure
64-
about what to hack on!
65-
Please see: [TODO.md](TODO.md) for a list of upcoming work and TODO items.
66-
Please get involved by working on one of these items or by suggesting something
67-
else!
114+
about what to hack on! Please get involved by working on one of these items or
115+
by suggesting something else!
68116

69117
## Bugs:
70118

71119
Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/blob/master/main.go)
72120
to `true`, and post the logs when you report the [issue](https://github.com/purpleidea/mgmt/issues).
73-
Bonus points if you provide a [shell](https://github.com/purpleidea/mgmt/tree/master/test/shell)
74-
or [OMV](https://github.com/purpleidea/mgmt/tree/master/test/omv) reproducible
75-
test case.
76121
Feel free to read my article on [debugging golang programs](https://purpleidea.com/blog/2016/02/15/debugging-golang-programs/).
77122

78123
## Patches:

‎docs/development.md

Lines changed: 115 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,118 @@ developing `mgmt`. Useful tools, conventions, etc.
55

66
Be sure to read [quick start guide](quick-start-guide.md) first.
77

8+
## Vagrant
9+
10+
If you would like to avoid doing the above steps manually, we have prepared a
11+
[Vagrant](https://www.vagrantup.com/) environment for your convenience. From the
12+
project directory, run a `vagrant up`, and then a `vagrant status`. From there,
13+
you can `vagrant ssh` into the `mgmt` machine. The `MOTD` will explain the rest.
14+
This environment isn't commonly used by the `mgmt` developers, so it might not
15+
be working properly.
16+
17+
## Using Docker
18+
19+
Alternatively, you can check out the [docker-guide](docker-guide.md) in order to
20+
develop or deploy using docker. This method is not endorsed or supported, so use
21+
at your own risk, as it might not be working properly.
22+
23+
## Information about dependencies
24+
25+
Software projects have a few different kinds of dependencies. There are _build_
26+
dependencies, _runtime_ dependencies, and additionally, a few extra dependencies
27+
required for running the _test_ suite.
28+
29+
### Build
30+
31+
* `golang` 1.11 or higher (required, available in some distros and distributed
32+
as a binary officially by [golang.org](https://golang.org/dl/))
33+
34+
### Runtime
35+
36+
A relatively modern GNU/Linux system should be able to run `mgmt` without any
37+
problems. Since `mgmt` runs as a single statically compiled binary, all of the
38+
library dependencies are included. It is expected, that certain advanced
39+
resources require host specific facilities to work. These requirements are
40+
listed below:
41+
42+
| Resource | Dependency | Version | Check version with |
43+
|----------|-------------------|-----------------------------|-----------------------------------------------------------|
44+
| augeas | augeas-devel | `augeas 1.6` or greater | `dnf info augeas-devel` or `apt-cache show libaugeas-dev` |
45+
| file | inotify | `Linux 2.6.27` or greater | `uname -a` |
46+
| hostname | systemd-hostnamed | `systemd 25` or greater | `systemctl --version` |
47+
| nspawn | systemd-nspawn | `systemd ???` or greater | `systemctl --version` |
48+
| pkg | packagekitd | `packagekit 1.x` or greater | `pkcon --version` |
49+
| svc | systemd | `systemd ???` or greater | `systemctl --version` |
50+
| virt | libvirt-devel | `libvirt 1.2.0` or greater | `dnf info libvirt-devel` or `apt-cache show libvirt-dev` |
51+
| virt | libvirtd | `libvirt 1.2.0` or greater | `libvirtd --version` |
52+
53+
For building a visual representation of the graph, `graphviz` is required.
54+
55+
To build `mgmt` without augeas support please run:
56+
`GOTAGS='noaugeas' make build`
57+
58+
To build `mgmt` without libvirt support please run:
59+
`GOTAGS='novirt' make build`
60+
61+
To build `mgmt` without docker support please run:
62+
`GOTAGS='nodocker' make build`
63+
64+
To build `mgmt` without augeas, libvirt or docker support please run:
65+
`GOTAGS='noaugeas novirt nodocker' make build`
66+
67+
## OSX/macOS/Darwin development
68+
69+
Developing and running `mgmt` on macOS is currently not supported (but not
70+
discouraged either). Meaning it might work but in the case it doesn't you would
71+
have to provide your own patches to fix problems (the project maintainer and
72+
community are glad to assist where needed).
73+
74+
There are currently some issues that make `mgmt` less suitable to run for
75+
provisioning macOS. But as a client to provision remote servers it should run
76+
fine.
77+
78+
Since the primary supported systems are Linux and these are the environments
79+
tested, it is wise to run these suites during macOS development as well. To ease
80+
this, Docker can be leveraged ([Docker for Mac](https://docs.docker.com/docker-for-mac/)).
81+
82+
Before running any of the commands below create the development Docker image:
83+
84+
```
85+
docker/scripts/build-development
86+
```
87+
88+
This image requires updating every time dependencies (`make-deps.sh`) changes.
89+
90+
Then to run the test suite:
91+
92+
```
93+
docker run --rm -ti \
94+
-v $PWD:/go/src/github.com/purpleidea/mgmt/ \
95+
-w /go/src/github.com/purpleidea/mgmt/ \
96+
purpleidea/mgmt:development \
97+
make test
98+
```
99+
100+
For convenience this command is wrapped in `docker/scripts/exec-development`.
101+
102+
Basically any command can be executed this way. Because the repository source is
103+
mounted into the Docker container invocation will be quick and allow rapid
104+
testing, for example:
105+
106+
```
107+
docker/scripts/exec-development test/test-shell.sh load0.sh
108+
```
109+
110+
Other examples:
111+
112+
```
113+
docker/scripts/exec-development make build
114+
docker/scripts/exec-development ./mgmt run --tmp-prefix lang examples/lang/load0.mcl
115+
```
116+
117+
Be advised that this method is not supported and it might not be working
118+
properly.
119+
8120
## Testing
9121

10122
This project has both unit tests in the form of golang tests and integration
@@ -45,5 +157,6 @@ individual tests to run.
45157

46158
### IDE/Editor support
47159

48-
- Emacs: see `misc/emacs/`
49-
- [Textmate](https://github.com/aequitas/mgmt.tmbundle)
160+
* Emacs: see `misc/emacs/`
161+
* [Textmate](https://github.com/aequitas/mgmt.tmbundle)
162+
* [VSCode](https://github.com/aequitas/mgmt.vscode)

0 commit comments

Comments
 (0)