Merge pull request #2 from resin-io/develop

Initial code PR

.gitignore

@@ -1,3 +1,4 @@
-# Ignore javascript files
-*.js
 node_modules/
+
+src/**/*.js
+tests/**/*.js

README.md

@@ -0,0 +1,103 @@
+# Resin-docker-build
+
+A modular, plugin-based approach to building docker containers. Resin-docker-build uses streams and
+hooks to provide a system which can be added to a build pipeline easily. With a simple but flexible
+interface, this module is meant to take the pain out of automating docker builds. Resin-docker-build is
+written in typescript, and all defined types are exported.
+
+## API
+
+All building is done via the `Builder` object.
+
+The `Builder` API has two top-level methods, which are used to trigger builds;
+
+* `createBuildStream(buildOpts: Object, hooks: BuildHooks): ReadWriteStream`
+
+Initialise a docker daemon and set it up to wait for some streaming data. The stream is returned to the
+caller for both reading and writing. Success and failure callbacks are provided via the hooks interface
+(see below). `buildOpts` is passed directly to the docker daemon and the expected input by the daemon is
+is a tar stream.
+
+* `buildDir(directory: string, buildOpts: Object, hooks: BuildHooks): ReadWriteStream`
+
+Inform the docker daemon to build a directory on the host. A stream is returned for reading, and
+the same success/failure callbacks apply. `buildOpts` is passed directly to the docker daemon.
+
+## Hooks
+
+Currently the hooks supported are;
+
+* `buildStream(stream: ReadWriteStream): void`
+
+Called by the builder when a stream is ready to communicate directly with the daemon. This is useful
+for parsing/showing the output and transforming any input before providing it to the docker daemon.
+
+* `buildSuccess(imageId: string, layers: string[]): void`
+
+Called by the builder when the daemon has successfully built the image. `imageId` is the sha digest provided
+by the daemon, which can be used for pushing, running etc. `layers` is a list of sha digests pointing to
+the intermediate layers used by docker. Can be useful for cleanup.
+
+* `buildFailure(error: Error)`
+
+Called by the builder when a build has failed for whatever reason. The reason is provided as a standard
+node error object. This was also close the build stream. No more hooks will be called after this.
+
+## Examples
+
+Examples are provided in typescript.
+
+### Directory Building
+
+```javascript
+import { Builder, BuildHooks } from 'resin-docker-build'
+
+const builder = new Builder({ socketPath: '/var/run/docker.sock' })
+
+const hooks: BuildHooks = {
+	buildStream: (stream: NodeJS.ReadWriteStream): void => {
+		stream.pipe(process.stdout)
+	},
+	buildSuccess: (imageId: string, layers: string[]): void => {
+		console.log(`Successful build! ImageId: ${imageId}`)
+	},
+	buildFailure: (error: Error): void => {
+		console.error(`Error building container: ${error}`)
+	}
+}
+
+builder.buildDir('./my-dir', {}, hooks)
+```
+
+### Building a tar archive
+```javascript
+import * as fs from 'fs'
+import { Builder, BuildHooks } from 'resin-docker-build'
+
+const builder = new Builder({ socketPath: '/var/run/docker.sock' })
+
+const getHooks = (archive: string): BuildHooks => {
+	return {
+		buildSuccess: (imageId: string, layers: string[]): void => {
+			console.log(`Successful build! ImageId: ${imageId}`)
+		},
+		buildFailure: (error: Error): void => {
+			console.error(`Error building container: ${error}`)
+		},
+		buildStream: (stream: NodeJS.ReadWriteStream): void => {
+			// Create a stream from the tar archive.
+			// Note that this stream could be from a webservice,
+			// or any other source. The only requirement is that
+			// when consumed, it produces a valid tar archive
+			const tarStream = fs.createReadStream(archive)
+
+			// Send the tar stream to the docker daemon
+			tarStream.pipe(stream)
+
+			stream.pipe(process.stdout)
+		}
+	}
+}
+
+builder.createBuildStream({}, getHooks('my-archive.tar'))
+```

gulpfile.js

@@ -0,0 +1,33 @@
+const gulp = require('gulp')
+const gutil = require('gulp-util')
+const gclean = require('gulp-clean')
+const typescript = require('gulp-typescript')
+const sourcemaps = require('gulp-sourcemaps')
+const tsProject = typescript.createProject('tsconfig.json')
+
+const OPTIONS = {
+	dirs: {
+		sources: './src',
+		build: './lib'
+	}
+}
+
+gulp.task('clean', () => {
+	return gulp.src(OPTIONS.dirs.build, { read: false })
+		.pipe(gclean())
+})
+
+gulp.task('typescript', () => {
+	tsProject.src()
+	.pipe(sourcemaps.init())
+	.pipe(tsProject()).on('error', gutil.log)
+	.pipe(sourcemaps.write('./', {
+		includeContent: true,
+		sourceRoot: OPTIONS.dirs.sources,
+		rootDir: '.'
+	}))
+	.pipe(gulp.dest(OPTIONS.dirs.build))
+})
+
+gulp.task('build', ['typescript'])
+gulp.task('default', ['build'])