Merge pull request #42 from slack/docker-serve

Update README and interactive Docker serve

Author: Jason Hansen

Dockerfile

@@ -6,4 +6,4 @@ WORKDIR /app
 RUN pip install -r requirements.txt
 
 EXPOSE 8000
-CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"]
+ENTRYPOINT ["mkdocs", "serve", "-a", "0.0.0.0:8000"]

Makefile

@@ -6,12 +6,25 @@ BUILDDIR        = _build
 MKDOCS          = mkdocs
 MKDOCSBUILDOPTS = --clean --strict --verbose
 MKDOCSBUILD     = $(MKDOCS) build $(MKDOCSBUILDOPTS)
+MKDOCSSERVE     = $(MKDOCS) serve -a 0.0.0.0:8000
+
+SHORT_NAME ?= docs-v2
+VERSION ?= git-$(shell git rev-parse --short HEAD)
+IMAGE := ${SHORT_NAME}:${VERSION}
+
+REPO_PATH := github.com/deis/${SHORT_NAME}
+DEV_ENV_WORK_DIR := /src/${REPO_PATH}
+DEV_ENV_PREFIX := docker run --rm -v ${CURDIR}:${DEV_ENV_WORK_DIR} -w ${DEV_ENV_WORK_DIR} -p 8000:8000
+DEV_ENV_CMD := ${DEV_ENV_PREFIX} ${DEV_ENV_IMAGE}
 
 build:
 	$(MKDOCSBUILD) --site-dir $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+serve:
+	$(MKDOCSSERVE)
+
 clean:
 	rm -rf $(BUILDDIR)/*
 
@@ -22,3 +35,9 @@ test: build
 	grep -q '<h1 id="welcome">Welcome</h1>' _build/html/index.html
 	@echo
 	@echo "Test finished. The HTML pages are in $(BUILDDIR)/html."
+
+docker-build:
+	docker build --rm -t ${IMAGE} .
+
+docker-serve:
+	${DEV_ENV_CMD} ${IMAGE}

README.md

@@ -1,66 +1,36 @@
-# Deis Workflow v2
+# Deis Workflow Documentation
 
-[![Build Status](https://travis-ci.org/deis/workflow.svg?branch=master)](https://travis-ci.org/deis/workflow) [![Go Report Card](http://goreportcard.com/badge/deis/workflow)](http://goreportcard.com/report/deis/workflow)
+## About
 
 Deis (pronounced DAY-iss) is an open source PaaS that makes it easy to deploy and manage
 applications on your own servers. Deis builds on [Kubernetes](http://kubernetes.io/) to provide
 a lightweight, [Heroku-inspired](http://heroku.com) workflow.
 
-## Work in Progress
+This repository represents the documentation for Deis Workflow which is the
+second major release of the Platform.
 
-![Deis Graphic](https://s3-us-west-2.amazonaws.com/get-deis/deis-graphic-small.png)
+## Requirements
 
-Deis Workflow v2 is currently in alpha. Your feedback and participation are more than welcome, but be
-aware that this project is considered a work in progress.
+The documentation site requires either a local installation of [MkDocs][] or
+access to Docker.
 
-The following features are not ready in Alpha1, but will be coming
-soon.
+### Local Installation
 
-- Complete SSL support
-- Dockerfile builds
-- Backup and restore features
-- Persistent storage (though it can be manually configured)
+Install [MkDocs][] and required dependencies:
 
-## Hacking Workflow
-
-First, [obtain a Kubernetes cluster][install-k8s]. Deis Workflow currently targets Kubernetes
-v1.1 with the following requirements:
-
-* Configure Docker's `insecure-registry` parameter to include the subnets used by your Kubernetes installation
-* If you are testing the logger components, you must enable `DaemonSet` experimental APIs via `--runtime-config=extensions/v1beta1/daemonsets=true`
-
-Next, install [helm](http://helm.sh). Next, add the deis repository to your chart list:
-
-```console
-$ helm repo add deis https://github.com/deis/charts
 ```
-
-Then, install Deis!
-
-```console
-$ helm install deis/deis
+make deps
 ```
 
-Complete instructions for installing and managing a Deis cluster are
-available in the [docs folder](https://github.com/deis/workflow/tree/master/docs/src).
-
-If you want to retrieve the latest client dev build for OS X or Linux, download the client:
+## Building Documentation
 
-```console
-$ curl -sSL http://deis.io/deis-cli/install-v2-alpha.sh | bash
-```
+To build the documentation run: `make build` or `make docker-build`
 
-If you want to hack on a new feature, build the deis/workflow image and push it to a Docker
-registry. The `$DEIS_REGISTRY` environment variable must point to a registry accessible to your
-Kubernetes cluster. You may need to configure the Docker engines on your Kubernetes nodes to allow
-`--insecure-registry 192.168.0.0/16` (or the appropriate address range).
+## Serve Documentation
 
-```console
-$ make docker-build docker-push
-```
+To serve documenation run: `make serve` or `make docker-serve`
 
-You'll want to modify the deis chart to use your custom image, then run `helm install` on the
-chart.
+Then view the documentation on [http://localhost:8000](http://localhost:8000) or `http://DOCKER_IP:8000`.
 
 ## License
 
@@ -72,3 +42,4 @@ Unless required by applicable law or agreed to in writing, software distributed
 
 
 [install-k8s]: http://kubernetes.io/gettingstarted/
+[mkdocs]: http://www.mkdocs.org/