ogb912/micromdm
1
0
Fork 0
mirror of https://github.com/micromdm/micromdm/ synced 2026-08-06 01:06:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update README and CONTRIBUTING docs (#200)

Browse Source
This commit is contained in:
Jesse Peterson
2017-05-31 11:14:57 -07:00
committed by GitHub
parent 7150bf083b
commit 42c074e678
2 changed files with 58 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
CONTRIBUTING.md
View File

@@ -1,21 +1,23 @@
# Contributing
Welcome, if you're looking to help, this document is a great place to start!
Welcome! If you're looking to help, this document is a great place to start!
# Finding Things That Need Help
## Finding things that need help
Here's a few places to get started and find out what's outstanding.
If you're looking to help, this is a great place to start.
- Read through the [MDM Protocol Reference](https://developer.apple.com/library/content/documentation/Miscellaneous/Reference/MobileDeviceManagementProtocolRef/3-MDM_Protocol/MDM_Protocol.html) on the Apple website. Having a deeper understanding of MDM can help with designing features and uncovering bugs.
- Follow the [Quickstart](https://github.com/micromdm/micromdm/wiki/Quickstart) guide and make edits if something doesn't look right.
- If you run into a problem that you're not sure how to fix, file a bug.
- Browse through the open issues. We try to tag issues as [**beginner friendly**](https://github.com/micromdm/micromdm/issues?q=is%3Aissue+is%3Aopen+label%3Abeginner-friendly) where appropriate.
- Follow the [Quickstart](https://github.com/micromdm/micromdm/wiki/Quickstart) guide and make edits if something doesn't look or work right.
- If you run into a problem that you're not sure how to fix, file a bug in [the issue tracker](https://github.com/micromdm/micromdm/issues)
- Browse through the open issues in [the issue tracker](https://github.com/micromdm/micromdm/issues). We try to tag issues as [**beginner friendly**](https://github.com/micromdm/micromdm/issues?q=is%3Aissue+is%3Aopen+label%3Abeginner-friendly) where appropriate.
- See something that others might benefit from? Considering updating or writing a [wiki page](https://github.com/micromdm/micromdm/wiki).
# Building the project
## Building the project
To build MicroMDM from source, you will need [Go 1.8](https://golang.org/dl/) or later installed.
To build MicroMDM from source, you will need [Go 1.8](https://golang.org/dl/) or later installed.
## If you have Go
## Once you have Go
MicroMDM uses the go lang `dep` tool for vendor management.
Use `which dep` to verify you have it installed and in your PATH.
@@ -23,43 +25,44 @@ If `dep` is not installed please review the [If you're new to Go](#if-youre-new-
1. `go get github.com/micromdm/micromdm`
2. `cd $GOPATH/src/github.com/micromdm/micromdm`
3. `dep ensure` install the necessary dependencies into /vendor folder
3. `dep ensure` install the necessary dependencies into the `/vendor` folder
4. `go build` or `go install`
## If you're new to Go
Go is a bit different from other languages in its requirements for how it expects its programmers to organize Go code on a system.
First, Go expects you to choose a folder, called a workspace (you can name it anything you'd like). The path to this folder must always be set in an environment variable - `GOPATH` (example: `GOPATH=/Users/groob/code/go`)
Your `GOPATH` must have thee subfolders - `bin`, `pkg` and `src`, and any code you create must live inside the `src` folder. It's also helpful to add `$GOPATH/bin` to your environment's `PATH` as that is where `go install` will place go binaries that you build.
Go is a bit different from other languages in its requirements for how it expects its programmers to organize Go code files in directories.
First, Go requires a folder, called a workspace (you can name it anything you'd like) to exist for go source, dependencies, etc. Before Go 1.8 the path to this folder must always be set in the environment variable `GOPATH` (example: `export GOPATH=/Users/groob/code/go`). As of Go 1.8 the default `GOPATH` is set to `$HOME/go` but you can still set it to whatever you like.
Your `GOPATH` must have thee subfolders: `bin`, `pkg`, and `src`. Any code you create must live inside the `src` folder. It's also helpful to add `$GOPATH/bin` to your environment's `PATH` as that is where `go install` will place go binaries that you build. This makes it so that binaries that are insalled can just be invoked by name rather than their full page.
Note: As of Go 1.8 the default `GOPATH` is set to `$HOME/go`.
A few helpful resources for getting started with Go.
A few helpful resources for getting started with Go:
* [Writing, building, installing, and testing Go code](https://www.youtube.com/watch?v=XCsL89YtqCs)
* [Resources for new Go programmers](http://dave.cheney.net/resources-for-new-go-programmers)
* [How I start](https://howistart.org/posts/go/1)
* [How to write Go code](https://golang.org/doc/code.html)
* [GOPATH - go wiki page](https://github.com/golang/go/wiki/GOPATH)
* [GOPATH on the go wiki](https://github.com/golang/go/wiki/GOPATH)
To build MicroMDM you will need to:
1. Download and install [`Go`](https://golang.org/dl/)
2. Install [`dep`](https://github.com/golang/dep) via `go get -u github.com/golang/dep/...`
2. Make a workspace directory and set the `GOPATH` as explained above.
3. Install [`dep`](https://github.com/golang/dep) via the command `go get -u github.com/golang/dep/...`
Note that `dep` is a very new project itself. If you're running trouble with the `dep ensure` command, ping @groob in the #micromdm channel on Slack.
3. Set the `GOPATH` as explained above.
4. `mkdir -p $GOPATH/src/github.com/micromdm`
5. `git clone` the project into the above folder.
The repo must always be in the folder `$GOPATH/src/github.com/micromdm/micromdm` even if you forked the project. Add a git remote to your fork.
5. `git clone git@github.com:micromdm/micromdm.git` the project into the above folder.
The repo must always be in the folder `$GOPATH/src/github.com/micromdm/micromdm` even if you forked the project. Add a git remote to your fork to track upstream.
6. `dep ensure` The `dep` command will download and install all necessary dependencies for the project to compile.
7. `go build` or `go install`
8. File an issue or a pull request if the instructions were unclear.
8. File an issue or a pull request if the instructions are unclear or problems pop-up for you.
# Important libraries and frameworks
## Important libraries and frameworks
MicroMDM is built using a few popular Go packages outside the standard libraries. It might be worth checking them out.
- [Go Kit](https://github.com/go-kit/kit#go-kit------) is a set of Go libraries used by MicroMDM to provide [logging](https://github.com/go-kit/kit/tree/master/log), and abstractions for building HTTP services. Its [examples](https://gokit.io/examples/) page is a good place to start.
- [BoltDB](https://github.com/boltdb/bolt#getting-started) is a key/value database used to provide persistant storage for many components of MicroMDM.
- [gorilla/mux](http://www.gorillatoolkit.org/pkg/mux) is used to provide routing for http handlers.
## Other resources
Also see [Contributing wiki page](https://github.com/micromdm/micromdm/wiki/Contributing) which has some additional notes on running, troubleshooting, and developing with MicroMDM.

63
README.md
View File

@@ -1,59 +1,59 @@
# MicroMDM - a devops friendly MDM server
[![CircleCI](https://circleci.com/gh/micromdm/micromdm/tree/master.svg?style=svg)](https://circleci.com/gh/micromdm/micromdm/tree/master)
MicroMDM is a Mobile Device Management server for Apple Devices (primarily macOS devices).
MicroMDM is a Mobile Device Management server for Apple Devices currently focused on managing macOS.
# Introduction
## Introduction
MDM is a large domain, and we are looking at how to solve many problems with device management. However, at this stage of development we're focusing on a very specific use case which is current to many Mac Administrators:
MDM is a large problem domain, and we are looking at how to solve many problems with device management and obstacles with existing solutions. However, at this stage of development we're focusing on a very specific use case which is current to many Mac Administrators:
> When a device enrolls(through DEP or otherwise) we want to bootstrap some tools to manage the mac. These are agents running on a mac like Munki or Chef/Puppet which will manage the software and configuration through the lifecycle of the mac.
> When a device enrolls (through DEP or otherwise) we want to bootstrap some tools to manage the Mac. These are agents running on a mac like Munki or Chef/Puppet which will manage the software and configuration through the lifecycle of the Mac.
MicroMDM, today is able to solve this common use-case, and we're focusing on improving the user experience for administrators and developing related features.
MicroMDM is able to solve this common use-case today, and we're focusing on improving the user experience for administrators and developing related features.
MicroMDM is being actively developed but is **ready for you to start testing**.
MicroMDM is being actively developed but is **ready for you to start testing**.
To get started, see the [Quickstart](https://github.com/micromdm/micromdm/wiki/Quickstart) tutorial on the wiki.
# Install
## Installing
Unless you're a developer, you probably want a binary you can run. [Download](https://github.com/micromdm/micromdm/releases/latest) the latest release,
either for macOS(darwin) or linux.
Unless you're a developer, you probably want a binary you can run. [Download](https://github.com/micromdm/micromdm/releases/latest) the latest release, either for macOS (darwin) or linux.
## Getting Help
# Getting Help
The best place to get help is the `#micromdm` channel on the MacAdmins Slack team. Join us there by following getting an [invitation here](https://macadmins.herokuapp.com/).
The best place to get help is the `#micromdm` channel on the MacAdmins Slack. [[invite link](https://macadmins.herokuapp.com/)]
# Helping Us
## Helping out
Over the last year this project has gained a lot of interest from the community. We want to make it clear that at this point MicroMDM is a passion project, and is being developed by a [few fellow Mac Admins](https://github.com/micromdm/micromdm/graphs/contributors) on weekends and during conference hackathons.
It would be great to get a few more developers to contribute, but at this point, there are _more_ important tasks than knowing how to code.
Here is how you can help:
It would be great to get a few more developers to contribute, but at this point, there are _more_ important tasks than knowing how to code. Here is how you can help:
- Read the documentation, install the tool and test MicroMDM.
- Read the documentation, install the tool and test MicroMDM.
- File bugs: https://github.com/micromdm/micromdm/issues
- Participate in discussions. The `#micromdm` slack channel is best, but `#mdm` and `#dep` are a few relevant ones.
- Edit the Wiki: https://github.com/micromdm/micromdm/wiki
The wiki page is open to anyone and you can make a lot of impact on the project by submitting additional documentation or even design proposals.
- Were you able to set up MicroMDM and enroll a few devices? Try blogging about your experience.
It can help others get started, or can help us figure out what we need to do better.
- Edit the [project Wiki](https://github.com/micromdm/micromdm/wiki). The wiki page is open to anyone and you can make a lot of impact on the project by submitting additional documentation or designing proposals.
- Were you able to set up MicroMDM and enroll a few devices? Blogging about your experience. It can help others get started, or can help us figure out what we need to do better.
See the [CONTRIBUTING](CONTRIBUTING.md) page for additional info.
# Design Goals
## Design Goals
As mentioned in the introduction, we are working on trying to solve the use case of bootstraping Macs. That's the short term (from now until WWDC).
But there's a larger design goal we have in mind - what will differentiate MicroMDM from other vendor projects. Here it is in brief:
As mentioned in the introduction, a primary use case is bootstraping Macs. That's the short term (from now until WWDC).
But there's a larger design goal we have in mind — what will differentiate MicroMDM from other vendor projects. Here it is in brief:
> MicroMDM aims to provide a declarative approach to device management. Too often vendor tools expect you to manage devices by filling out various forms in a web interface. While MicroMDM might have a web interface of it's own one day, the tool itself is inspired by popular DevOps processes like Configuration Management (chef/puppet/ansible, terraform) and orchestration frameworks (Kubernetes, Docker).
For example here is a process of applying a DEP profile (not to be confused with an Apple Configuration Profile, of course):
- MicroMDM aims to provide a declarative approach to device management. Too often vendor tools expect you to manage devices by filling out various forms in a web interface. While MicroMDM might have a web interface of it's own one day, the tool itself is inspired by popular DevOps processes like Configuration Management(chef/puppet/ansible,terraform) and orchestration frameworks(Kubernetes, Docker).
For example here is a process of applying a DEP profile:
```
$ micromdm apply dep-profile -f /tmp/profile.json
updated profile CDACFE6013F926F5.
$ mdmctl apply dep-profiles -template > /tmp/profile.json
$ micromdm get dep profile -uuid=CDACFE6013F926F5
$ mdmctl apply dep-profiles -f /tmp/profile.json
Defined DEP Profile with UUID 4B05B09E8AC7E7FC12C8F3338E099310
$ mdmctl get dep-profiles -f - -uuid=4B05B09E8AC7E7FC12C8F3338E099310
{
"profile_name": "Test Profile",
"url": "https://mdm.acmeinc.com/getconfig",
@@ -69,8 +69,7 @@ $ micromdm get dep profile -uuid=CDACFE6013F926F5
}
```
- Expose an API for developers and administratos. Today you can send MDM commands to the server using a RESTful API. We intend to make more processes scriptable.
- Provide a way for administrators to subscribe to events. MicroMDM works through a pubsub system at it's core. For example, when a new device enrolls into the MDM, the server doesn't record this in the database immediately, but instead creates an event which is sent on a message bus to other services. Today, this message bus is built in-memory, but we plan to expose the same hooks over the network, allowing developers to consume events in any language - not just Go.
- Expose an API for developers and administratos. Today you can send MDM commands to the server using a RESTful API. We intend to make more processes scriptable.
- Provide a way for administrators to subscribe to events generated from the MDM interactions between client & server. MicroMDM works through a pubsub system at its core. For example, when a new device enrolls with the MDM server it doesn't record this in the database immediately, but instead creates an event which is sent on the message bus to other services that are listening. Today, this message bus is built in-memory, but we plan to expose the same hooks over the network, allowing developers to consume events in any language — not just Go.
[Here](https://docs.google.com/drawings/d/1B4w5xOmU-7D5pcW0kdiY7ia5fl7UnBfRpWR8KxzD1YI/edit?usp=sharing) is a slightly more in depth design overview of the pubsub system within MicroMDM.