Merge pull request #183 from pmorie/docs

Merged by openshift-bot

cleanup/cmd/cmd.go

@@ -1,3 +1,6 @@
+/*
+The gear 'clean' extension.
+*/
 package cmd
 
 import (

cleanup/doc.go

@@ -0,0 +1,4 @@
+/*
+ Provides cleanup tools for orphaned ports, unit files, etc.
+*/
+package cleanup

cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides the 'gear' binary extension mechanism and remote execution infrastructure.
+*/
+package cmd

cmd/gear/doc.go

@@ -0,0 +1,4 @@
+/*
+The `gear` binary variations for linux, darwin, and windows.
+*/
+package main

cmd/sti/main.go

@@ -1,3 +1,6 @@
+/*
+The 'sti' binary.
+*/
 package main
 
 import (

cmd/switchns/main.go

@@ -1,6 +1,6 @@
-// An executable for executing a process inside a running Docker container.  Can be used as
-// root to switch into any named container (name is the same as the gear name), or as a
-// container user (user tied to a container) to enter the context for SSH or other function.
+// The switchns binary - an executable for executing a process inside a running Docker container.
+// Can be used as root to switch into any named container (name is the same as the gear name), or
+// as a container user (user tied to a container) to enter the context for SSH or other function.
 // Will be eventually become a setuid stub for docker exec.
 package main
 

config/doc.go

@@ -0,0 +1,5 @@
+/*
+Configuration items for geard internals and extension mechanism for registering required
+directories.
+*/
+package config

containers/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides implementation of core gear binary commands.
+*/
+package cmd

containers/http/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides http requests and handlers for container jobs.
+*/
+package http

containers/jobs/doc.go

@@ -0,0 +1,7 @@
+/*
+Job implementations for core API.  Container jobs control container related actions on a server.
+Each request object has a default implementation on Linux via systemd, and a structured response if
+necessary.  The Execute() method is separated so that client code and server code can share common
+sanity checks.
+*/
+package jobs

containers/jobs/jobs.go

@@ -1,7 +1,3 @@
-// Container jobs control container related actions on a server.  Each request
-// object has a default implementation on Linux via systemd, and a structured
-// response if necessary.  The Execute() method is separated so that client code
-// and server code can share common sanity checks.
 package jobs
 
 import (

containers/systemd/doc.go

@@ -0,0 +1,4 @@
+/*
+Systemd concerns for gears: unit files, socket activation, event subscriptions, etc.
+*/
+package systemd

containers/systemd/init/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'init' extension - setup environment for containers.
+*/
+package init

daemon/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'daemon' extension.
+*/
+package cmd

daemon/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides an extension mechanism for 'gear daemon'.
+*/
+package daemon

deployment/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides gear deployment and linking from a deployment descriptor.
+*/
+package deployment

dispatcher/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides Dispatcher, a reactor pattern implementation that processes jobs.
+*/
+package dispatcher

docker/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides utility methods for working with Docker.
+*/
+package docker

docs/code_structure.md

@@ -1,11 +1,80 @@
 geard code structure
 ====================
 
-Geard is a large project.  This is a rough map of each directory and its contents:
+Geard is a large project.  This doc will present the basic layout of the geard source and key 
+architectural patterns required to understand it.  Geard is written in Go; we recommend the 
+following resources for learning the language:
+
+*   [Golang tour](http://tour.golang.org/#1)
+*   [Effective Go](http://golang.org/doc/effective_go.html)
+*   [Go Language Specification](http://golang.org/ref/spec)
+
+key patterns
+------------
+
+#### Package vendoring
+
+Geard has many dependencies on other projects and uses vendoring to control which versions of these
+dependencies are used when the project is built.  The vendored sources are in the `vendor` package.
+The `contrib/build` script places the sources in this package in front of the system `GOPATH`,
+ensuring that the right versions are loaded regardless of the versions of our dependencies that may
+be installed in your local system.  We use the `contrib/vendor` script to maintain our vendored
+dependencies.
+
+#### The gear binary and extensions
+
+The `gear` binary is designed to implement a minimal set of core functionality (installing,
+starting, stopping containers, etc) and provide a registration point for arbitrary extensions. Many
+packages in the geard source supply extensions to this binary via a `cmd` subpackage.  Some
+examples from the [package map](#package-map) are:
+
+    geard/
+      git/                        # git repositories and their concerns:
+        cmd/                      #   gear 'create-repo' extension
+      ...
+      idler/                      # idler daemon and its concerns:
+        cmd/                      #   gear 'idler-daemon' extension
+      ...
+      router/                     # a test router implementation
+        cmd/                      #   gear 'test-router' extension
+
+The extension point is described in [`cmd/extension.go`]():
+
+    // Register flags and commands underneath a parent Command-
+    type CommandRegistration func(parent *cobra.Command)
+
+    // ...
+
+    // Register an extension to this server during init() or startup
+    func AddCommandExtension(ext CommandRegistration, local bool) {
+
+The convention for registering extensions is to create a `cmd` package with `CommandRegistration`
+functions.  The gear binary implementation for each supported platform handles calling 
+`AddCommandExtension` in its package `init` method.
+
+#### Request handling in the daemon
+
+The geard daemon - started with `gear daemon` presents a rest API for working with containers.
+Internally, requests to this API are fulfilled using an implementation of the 
+[reactor pattern](http://en.wikipedia.org/wiki/Reactor_pattern).  The reactor is called a 
+'dispatcher' in this project; the source is in the `dispatcher` package.  The reactor's units of
+work are called 'jobs' in this project; they are described in the `jobs` package.
+
+
+binaries built
+--------------
+
+    gear                          # Core binary + extensions
+    sti                           # Source-to-images (STI) binary
+    switchns                      # Switchns - change namespace into a container
+    gear-auth-keys-command        # 
+
+package map
+-----------
 
     geard/
       cleanup/                    # clean up tools - delete old unit files
-          cmd/                    #   gear 'clean' extension
+        cmd/                      #   gear 'clean' extension
       cmd/                        # various binaries built from geard source:
         gear/                     #   gear cli binary
         sti/                      #   source-to-images (sti) binary
@@ -15,7 +84,7 @@ Geard is a large project.  This is a rough map of each directory and its content
         http/                     #   http requests and handlers (glue code)
         jobs/                     #   job implementations for core API
         systemd/                  #   gears and systemd
-          init/                   #     gear init extension - setup the systemd fixtures
+          init/                   #     gear 'init' extension - setup the systemd fixtures
       contrib/                    # contributions - various scripts and fixtures
       deployment/                 # gear deployment/orchestration code
         fixtures/                 #   fixtures for deployment tests
@@ -25,23 +94,23 @@ Geard is a large project.  This is a rough map of each directory and its content
       encrypted/                  # encryption tokens and handlers for encrypted jobs
         fixtures/                 #   fixtures for encryption tests
       git/                        # git repositories and their concerns:
-        cmd/                      #   gear create-repo extension
+        cmd/                      #   gear 'create-repo' extension
         http/                     #   http requests and handlers (glue code)
         jobs/                     #   job implementations
       http/                       # http transport for jobs
       idler/                      # idler daemon and its concerns:
-        cmd/                      #   gear idler extension
+        cmd/                      #   gear 'idler-daemon' extension
         config/                   #   idler configuration
         iptables/                 #   change iptables rules for container idle/unidle
       jobs/                       # job framework (reactor units of work)
       pkg/                        # other projects in our group that geard depends on
       port/                       # port allocation and reservation
       router/                     # a test router implementation
-        cmd/                      #   gear test-router extension
+        cmd/                      #   gear 'test-router' extension
       selinux/                    # gears and selinux policies
         library/                  #   golang libselinux wrapper
       ssh/                        # container ssh
-        cmd/                      #   ssh binaries 
+        cmd/                      #   gear 'add-keys' and 'auth-keys-command' extensions
           gear-auth-keys-command/ #     gear-auth-keys-command binary
         http/                     #   http requests and handlers (glue code)
         jobs/                     #   job implementations

encrypted/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides encrypted tokens and handlers for encrypted jobs.
+*/
+package encrypted

git/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'create-repo' extension.
+*/
+package cmd

git/http/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides http request and handlers for git repo operations.
+*/
+package http

git/jobs/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides job implementations for git API calls.
+*/
+package jobs

http/doc.go

@@ -0,0 +1,4 @@
+/*
+HTTP transport for jobs.
+*/
+package http

idler/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'idler-daemon' extension.
+*/
+package cmd

idler/config/doc.go

@@ -0,0 +1,4 @@
+/*
+Idler daemon configuration.
+*/
+package config

idler/doc.go

@@ -0,0 +1,4 @@
+/*
+Idler daemon and its concerns.
+*/
+package idler

idler/iptables/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides iptables rules maintenance for gear idle/unidle.
+*/
+package iptables

jobs/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides the units of work, Jobs, for the reactor pattern implementation in the dispatcher package.
+*/
+package jobs

pkg/doc.go

@@ -0,0 +1,4 @@
+/*
+Other projects from the geard team that are dependencies of geard.
+*/
+package pkg

port/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides port allocation and reservation.
+*/
+package port

router/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'test-router' extension.
+*/
+package cmd

router/doc.go

@@ -0,0 +1,4 @@
+/*
+A test router implementation.
+*/
+package router

router/jobs/doc.go

@@ -0,0 +1,4 @@
+/*
+Job implementations for router operations.
+*/
+package jobs

selinux/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides SELinux support for gears.
+*/
+package selinux

selinux/library/selinux_impl.go

@@ -1,7 +1,5 @@
 // +build selinux
 
-package library
-
 /*
  The selinux package is a go bindings to libselinux required to add selinux
  support to docker.
@@ -11,6 +9,7 @@ package library
  Used some ideas/code from the go-ini packages https://github.com/vaughan0
  By Vaughan Newton
 */
+package library
 
 // #cgo pkg-config: libselinux
 // #include <selinux/selinux.h>

ssh/cmd/doc.go

@@ -0,0 +1,4 @@
+/*
+The gear 'auth-keys-command' extension.
+*/
+package cmd

ssh/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides ssh access to gears.
+*/
+package ssh

ssh/http/doc.go

@@ -0,0 +1,4 @@
+/*
+HTTP handlers for ssh-related jobs.
+*/
+package http

ssh/jobs/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides job implementations for ssh requests.
+*/
+package jobs

sti/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides functionality to build docker images from user source and a base image.
+*/
+package sti

systemd/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides utilities for working with systemd and the journal.
+*/
+package systemd

tests/doc.go

@@ -0,0 +1,4 @@
+/*
+Integration tests and associated fixtures and Dockerfiles.
+*/
+package tests

transport/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides an abstraction for job transport.
+*/
+package transport

utils/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides basic internal utilities for geard.
+*/
+package utils

vendor/doc.go

@@ -0,0 +1,4 @@
+/*
+Provides version-pinned dependencies.
+*/
+package vendor