From f1e0cfea1c36484023fbf369b4c5475a097379dd Mon Sep 17 00:00:00 2001 From: James Shubin Date: Mon, 16 Jan 2017 10:06:55 -0500 Subject: [PATCH] docs: Split out a separate quick start guide --- README.md | 43 --------------- docs/quick-start-guide.md | 111 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+), 43 deletions(-) create mode 100644 docs/quick-start-guide.md diff --git a/README.md b/README.md index e4339cef..33fcb320 100644 --- a/README.md +++ b/README.md @@ -25,29 +25,6 @@ With your help you'll be able to influence our design and get us there sooner! Please join the [#mgmtconfig](https://webchat.freenode.net/?channels=#mgmtconfig) IRC community! If you have a well phrased question that might benefit others, consider asking it by sending a patch to the documentation [FAQ](https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md#usage-and-frequently-asked-questions) section. I'll merge your question, and a patch with the answer! -## Quick start: -* Make sure you have golang version 1.6 or greater installed. -* If you do not have a GOPATH yet, create one and export it: -``` -mkdir $HOME/gopath -export GOPATH=$HOME/gopath -``` -* You might also want to add the GOPATH to your `~/.bashrc` or `~/.profile`. -* For more information you can read the [GOPATH documentation](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable). -* Next download the mgmt code base, and switch to that directory: -``` -go get -u github.com/purpleidea/mgmt -cd $GOPATH/src/github.com/purpleidea/mgmt -``` -* Run `make deps` to install system and golang dependencies. Take a look at `misc/make-deps.sh` for details. -* Run `make build` to get a freshly built `mgmt` binary. -* Run `time ./mgmt run --yaml examples/graph0.yaml --converged-timeout=5 --tmp-prefix` to try out a very simple example! -* To run continuously in the default mode of operation, omit the `--converged-timeout` option. -* Have fun hacking on our future technology! - -## Examples: -Please look in the [examples/](examples/) folder for more examples! - ## Documentation: Please see: the manually created [documentation.md](docs/documentation.md) (also available as [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/documentation.md)) and the automatically generated [GoDoc documentation](https://godoc.org/github.com/purpleidea/mgmt). @@ -61,26 +38,6 @@ Please set the `DEBUG` constant in [main.go](https://github.com/purpleidea/mgmt/ Bonus points if you provide a [shell](https://github.com/purpleidea/mgmt/tree/master/test/shell) or [OMV](https://github.com/purpleidea/mgmt/tree/master/test/omv) reproducible test case. Feel free to read my article on [debugging golang programs](https://ttboj.wordpress.com/2016/02/15/debugging-golang-programs/). -## Dependencies: -* golang 1.6 or higher (required, available in most distros) -* golang libraries (required, available with `go get`) -``` -go get github.com/coreos/etcd/client -go get gopkg.in/yaml.v2 -go get gopkg.in/fsnotify.v1 -go get github.com/urfave/cli -go get github.com/coreos/go-systemd/dbus -go get github.com/coreos/go-systemd/util -go get github.com/coreos/pkg/capnslog -go get github.com/libvirt/libvirt-go -``` -* stringer (optional for building), available as a package on some platforms, otherwise via `go get` -``` -go get golang.org/x/tools/cmd/stringer -``` -* pandoc (optional, for building a pdf of the documentation) -* graphviz (optional, for building a visual representation of the graph) - ## Patches: We'd love to have your patches! Please send them by email, or as a pull request. diff --git a/docs/quick-start-guide.md b/docs/quick-start-guide.md new file mode 100644 index 00000000..65d8cca4 --- /dev/null +++ b/docs/quick-start-guide.md @@ -0,0 +1,111 @@ +#mgmt + + + +##mgmt quick start guide +####Available from: +####[https://github.com/purpleidea/mgmt/](https://github.com/purpleidea/mgmt/) + +####This documentation is available in: [Markdown](https://github.com/purpleidea/mgmt/blob/master/docs/quick-start-guide.md) or [PDF](https://pdfdoc-purpleidea.rhcloud.com/pdf/https://github.com/purpleidea/mgmt/blob/master/docs/quick-start-guide.md) format. + +####Table of Contents + +1. [Dependencies](#dependencies) +2. [Quick start](#quick-start) +3. [Examples](#examples) +4. [Authors - Authors and contact information](#authors) + +## Dependencies: +Software projects have a few different kinds of dependencies. There are _build_ +dependencies, _runtime_ dependencies, and additionally, a few extra dependencies +required for running the _test_ suite. + +### Build +* `golang` 1.6 or higher (required, available in most distros) +* golang libraries (required, available with `go get ./...`) a partial list includes: +``` +github.com/coreos/etcd/client +gopkg.in/yaml.v2 +gopkg.in/fsnotify.v1 +github.com/urfave/cli +github.com/coreos/go-systemd/dbus +github.com/coreos/go-systemd/util +github.com/libvirt/libvirt-go +``` +* `stringer` (optional), available as a package on some platforms, otherwise via `go get` +``` +golang.org/x/tools/cmd/stringer +``` +* `pandoc` (optional), for building a pdf of the documentation + +###Runtime +A relatively modern GNU/Linux system should be able to run `mgmt` without any +problems. Since `mgmt` runs as a single statically compiled binary, all of the +library dependencies are included. It is expected, that certain advanced +resources require host specific facilities to work. These requirements are +listed below: + +| Resource | Dependency | Version | +|----------|-------------------|---------| +| file | inotify | ? | +| hostname | systemd-hostnamed | ? | +| nspawn | systemd-nspawn | ? | +| pkg | packagekitd | ? | +| svc | systemd | ? | +| virt | libvirtd | ? | + +For building a visual representation of the graph, `graphviz` is required. + +###Testing +* golint `github.com/golang/lint/golint` + +## Quick start: +* Make sure you have golang version 1.6 or greater installed. +* If you do not have a GOPATH yet, create one and export it: +``` +mkdir $HOME/gopath +export GOPATH=$HOME/gopath +``` +* You might also want to add the GOPATH to your `~/.bashrc` or `~/.profile`. +* For more information you can read the [GOPATH documentation](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable). +* Next download the mgmt code base, and switch to that directory: +``` +go get -u github.com/purpleidea/mgmt +cd $GOPATH/src/github.com/purpleidea/mgmt +``` +* Run `make deps` to install system and golang dependencies. Take a look at `misc/make-deps.sh` for details. +* Run `make build` to get a freshly built `mgmt` binary. +* Run `time ./mgmt run --yaml examples/graph0.yaml --converged-timeout=5 --tmp-prefix` to try out a very simple example! +* To run continuously in the default mode of operation, omit the `--converged-timeout` option. +* Have fun hacking on our future technology! + +## Examples: +Please look in the [examples/](../examples/) folder for some examples! + +##Authors +Copyright (C) 2013-2016+ James Shubin and the project contributors + +Please see the +[AUTHORS](https://github.com/purpleidea/mgmt/tree/master/AUTHORS) file +for more information. + +* [github](https://github.com/purpleidea/) +* [@purpleidea](https://twitter.com/#!/purpleidea) +* [https://ttboj.wordpress.com/](https://ttboj.wordpress.com/)