Merge pull request #492 from SvenDowideit/add-docs-plus-tooling

Import Kitematic documentation into docs.docker.com

Makefile

@@ -0,0 +1,22 @@
+.PHONY: docs docs-shell docs-build run
+
+# TODO: clearly need to note pre-req's - OSX and node installed? - see contributing docs
+run:
+	npm install
+	npm run
+
+# import the existing docs build cmds from docker/docker
+DOCS_MOUNT := $(if $(DOCSDIR),-v $(CURDIR)/$(DOCSDIR):/$(DOCSDIR))
+DOCSPORT := 8000
+GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null)
+DOCKER_DOCS_IMAGE := kitematic-docs$(if $(GIT_BRANCH),:$(GIT_BRANCH))
+DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT)
+
+docs: docs-build
+	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" mkdocs serve
+
+docs-shell: docs-build
+	$(DOCKER_RUN_DOCS) -p $(if $(DOCSPORT),$(DOCSPORT):)8000 "$(DOCKER_DOCS_IMAGE)" bash
+
+docs-build:
+	docker build -t "$(DOCKER_DOCS_IMAGE)" -f docs/Dockerfile .

docs/Dockerfile

@@ -0,0 +1,17 @@
+FROM docs/base:latest
+MAINTAINER Sven Dowideit <SvenDowideit@docker.com> (@SvenDowideit)
+
+# to get the git info for this repo
+COPY . /src
+
+# Reset the /docs dir so we can replace the theme meta with the new repo's git info
+#RUN git reset --hard
+
+RUN grep '"version"' /src/package.json  | sed 's/.*"version": "\(.*\)".*/\1/' > /docs/VERSION
+COPY docs/* /docs/sources/kitematic/
+# sadly, COPY is only recursive if you don't also need to name the destination
+COPY docs/assets/ /docs/sources/kitematic/assets/
+COPY docs/mkdocs.yml /docs/mkdocs-dhe.yml
+
+# Then build everything together, ready for mkdocs
+RUN /docs/build.sh

docs/faq.md

@@ -0,0 +1,65 @@
+page_title: Kitematic: Frequently Asked Questions
+page_description: Documentation covering common questions users have about Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui
+
+
+# Frequently Asked Questions
+
+### Is Kitematic Open Source?
+
+Yes! Our source code is available on
+[GitHub](https://github.com/kitematic/kitematic). Kitematic is open source
+software released under the Apache 2.0 license.
+
+### How can I contribute to Kitematic?
+
+We always welcome (and deeply appreciate!) new contributions to the project. The
+best way to start contributing to Kitematic is to review our doc on
+[contributing](https://github.com/kitematic/kitematic/blob/master/CONTRIBUTING.md).
+
+### How does Kitematic work with Docker?
+
+Kitematic connects directly do a running instance of Docker and controls it via
+the Docker Remote API.
+
+### Which platforms does Kitematic support?
+
+Right now Kitematic only works on Mac OS X. That said, Windows is on the
+short-term
+[roadmap](https://github.com/kitematic/kitematic/blob/master/ROADMAP.md) (coming
+soon!) and a Linux version is in high demand.
+
+### Why does Kitematic collect usage analytics and bug reports?
+
+Kitematic tracks anonymous errors and analytics to help understand why things go
+wrong and to help understand how users are interacting with the app so we can
+continuously make it better.
+
+You can opt-out of this anytime via the in-app preferences.
+
+#### What we DON'T collect
+
+- Personal information: any information that would allow us to determine a
+  specific user of Kitematic
+- Information or data relating to code, containers or Docker images opened via
+  Kitematic.
+
+#### What we DO collect
+
+- Anonymous events for actions in the app. We never collect data associated with
+  events. For example:
+  - User searched for images (but not what the search query was).
+  - User created a container (but not which image, the name of the container or
+    any data involved)
+  - User opened the preferences pane
+  - User deleted a container
+- Errors names, messages & stack traces (scrubbed for user names)
+- Operating System, Kitematic and installed VirtualBox versions
+
+We'd love to answer any more questions about this. Feel free to reach us at
+kitematic@docker.com or to open an issue on GitHub.
+
+## Next Steps
+
+For information about known issues in the current release of Kitematic, take a
+look at the [Known issues](./known-issues.md).

docs/index.md

@@ -0,0 +1,48 @@
+page_title: Kitematic User Guide: Intro & Overview
+page_description: Documentation that provides an overview of Kitematic and installation instructions
+page_keywords: docker, documentation, about, technology, kitematic, gui
+
+# Installing Kitematic
+
+You install Kitematic much the same way you install any application on a Mac or
+Windows PC: download an image and run an installer.
+
+## Download Kitematic
+
+[Download the Kitematic zip file](https://kitematic.com/download/), unzip the
+file by double-clicking it, and then double-click the application to run it.
+You'll probably also want to put the application in your Applications folder.
+
+## Initial Setup
+
+Opening Kitematic for the first time sets up everything you need to run Docker
+containers. If you don't already have VirtualBox installed, Kitematic will
+download and install the latest version.
+
+![Installing](./assets/installing.png)
+
+All Done! Within a minute you should be ready to start running your first
+container!
+
+![containers](./assets/containers.png)
+
+## Technical Details
+
+Kitematic is a self-contained .app, with a two exceptions:
+
+- It will install VirtualBox if it's not already installed.
+- It copies the `docker` and `docker-machine` binaries to `/usr/local/bin` for
+  convenience.
+
+### Why does Kitematic need my root password?
+
+Kitematic needs your root password for two reasons:
+
+- Installing VirtualBox requires root as it includes Mac OS X kernel extensions.
+- Copying `docker` and `docker-machine` to `/usr/local/bin` may require root
+  permission if the default permissions for this directory have been changed
+  prior to installing Kitematic.
+
+## Next Steps
+
+For information about using Kitematic, take a look at the [User Guide](./userguide.md).

docs/known-issues.md

@@ -0,0 +1,44 @@
+page_title: Kitematic Known Issues
+page_description: Information about known issues in Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui
+
+# Known Issues
+
+
+Kitematic is in beta, so we're still working out the kinks. The most common
+errors occur at the setup stage since creating a VM reliably with VirtualBox can
+be tricky. We are working on this problem.
+
+In the meantime, below are a list of common errors and solutions that work for
+most people.
+
+## Setup Error or Hanging at 99%
+
+Sometimes Kitematic doesn't set up VirtualBox properly. Retrying the setup
+usually works (via one of the two retry buttons). If not, try the following
+commands on the command line:
+
+- `docker-machine rm -f dev`
+- `docker-machine create -d virtualbox dev`
+
+Then re-open Kitematic. This usually fixes the issue, but if it persists, feel
+free to view our [existing GitHub
+issues](https://github.com/kitematic/kitematic/issues?q=is%3Aopen+is%3Aissue+label%3Abug).
+
+## Contributing Fixes
+
+We're always looking for help to make Kitematic better and more reliable! Visit
+[our GitHub page](https://github.com/kitematic/kitematic) for docs on how to
+contribute.
+
+Under the hood, Kitematic uses [Docker
+Machine](https://github.com/docker/machine) to provision Docker-enabled VMs via
+VirtualBox. We're still working on a stronger integration with this project.
+Their [GitHub repo](https://github.com/docker/machine) is a great place to start
+if you're looking to help fix specific issues around VM provisioning.
+
+## View All Issues
+
+For a full list of Kitematic bugs or issues see our [GitHub
+issues](https://github.com/kitematic/kitematic/issues?q=is%3Aopen+is%3Aissue+label%3Abug)
+labelled as `bug`.

docs/minecraft-server.md

@@ -0,0 +1,71 @@
+page_title: Kitematic Tutorial: Set up a Minecraft Server
+page_description: Tutorial demonstrating the setup of a Minecraft server using Docker and Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui, minecraft, tutorial
+
+# Kitematic tutorial: Set up a Minecraft server
+
+This is a quick tutorial demonstrating how to set up a local Minecraft server
+using Kitematic and Docker.
+
+### Create Minecraft Server Container
+
+First, if you haven't yet done so, [download and start
+Kitematic](./index.md). Once installed and running, the app should look like this:
+
+Create a container from the recommended Minecraft image by clicking the "Create"
+button.
+
+![create Minecraft container](../assets/minecraft-create.png)
+
+After the image finishes downloading, you'll see the home screen for the
+Minecraft container. Your Minecraft server is now up and running inside a Docker
+container. Note that we've marked the IP and port you can use to connect to
+your Minecraft server in red (your IP and port may be different from what's
+shown).
+
+![Minecraft server port and IP info](../assets/minecraft-port.png)
+
+### Connect to Minecraft server
+
+Open your Minecraft client, log in with your Minecraft account and click on the
+"Multiplayer" button.
+
+![Minecraft login screen](../assets/minecraft-login.png)
+
+Click the "Add Server" button to add the Minecraft server you want to connect
+to.
+
+![Add server](../assets/minecraft-login.png)
+
+Fill in the "Server Address" text box with the marked IP and port from Kitematic
+you saw earlier.
+
+![Minecraft server address](../assets/minecraft-server-address.png)
+
+Click on the play button to connect to your Minecraft server and enjoy!
+
+
+### Change map using Docker volume
+
+Open the "data" folder from Kitematic (You'll need to "Enable all volumes to edit
+files via Finder"). We use Docker Volume to map the folder from the Minecraft
+Docker container onto your computer.
+
+![Minecraft data volume](../assets/minecraft-data-volume.png)
+
+The Finder will open, allowing you to replace your current map with the new one
+you desire.
+
+![Minecraft maps](../assets/minecraft-map.png)
+
+Restart your container by clicking the "Restart" button.
+
+![Restart Minecraft container](../assets/minecraft-restart.png)
+
+Go back to your Minecraft client and join your server. The new map should load.
+
+
+## Next Steps
+
+For an example using Kitematic to run Nginx, take a look at the [Nginx web
+server](./nginx-web-server.md) page.

docs/mkdocs.yml

@@ -0,0 +1,13 @@
+
+# Kitematic
+- ['kitematic/index.md', 'Installation', 'Kitematic on OS X']
+
+- ['kitematic/userguide.md', 'User Guide', 'Kitematic']
+
+- ['kitematic/minecraft-server.md', 'Examples', 'Kitematic: Minecraft server']
+- ['kitematic/nginx-web-server.md', 'Examples', 'Kitematic: Ngnix web server']
+- ['kitematic/rethinkdb-dev-database.md', 'Examples', 'Kitematic: RethinkDB development database']
+
+- ['kitematic/faq.md', 'Reference', 'Kitematic: FAQ']
+- ['kitematic/known-issues.md', 'Reference', 'Kitematic: Known issues']
+

docs/nginx-web-server.md

@@ -0,0 +1,80 @@
+page_title: Kitematic Tutorial: Set up an Nginx web server
+page_description: Tutorial demonstrating the setup of an Nginx web server using Docker and Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui, nginx, tutorial
+
+# Serving a Static Website with Nginx
+
+In this tutorial, you will:
+
+- Download and run a web server container
+- Explore the container's website data natively on your Mac
+- Use volumes to modify the website data
+
+In this example website we'll be serving the popular 2048 game, as shown below.
+Let's get to it!
+
+![2048 game](../assets/nginx-2048.png)
+
+#### Running the Nginx Web Server Container
+
+First, if you haven't yet done so, [download and start
+Kitematic](./index.md). Once installed and running, the app should look like this:
+
+![Nginx create](../assets/nginx-create.png)
+
+Click on the _Create_ button of the `hello-world-nginx` listing as shown above.
+Kitematic will download (also known as pull the image) and then run a tiny Nginx web server
+in a Docker container, allowing it to serve website data to your Mac.
+
+![download Nginx hello world](../assets/nginx-hello-world.png)
+
+Once it's done downloading you should see a quick preview of the example website
+that comes with the container, as shown below. Click on the preview to see the
+result in your own browser.
+
+![Nginx preview](../assets/nginx-preview.png)
+
+**What just happened?** Kitematic downloaded the `kitematic/hello-world-nginx`
+image from the Docker Hub and then created and ran a Docker Nginx container from
+this image.
+
+#### Viewing the Website Data in Finder
+
+This container exposes website data via a _Docker volume_. Kitematic makes
+managing Docker volumes easy - you can edit the data in Finder or with your
+favorite text editor. By default, Kitematic places volumes under `~/Kitematic`
+but you can change this in the container settings. To access the files via
+finder, click on the in-app folder icon for a container and "Enable all volumes
+to edit via Finder":
+
+![Nginx data volume](../assets/nginx-data-volume.png)
+
+A Finder window of the folder should open containing the index.html file we see
+being served by the container.
+
+![Nginx data folder](../assets/nginx-data-folder.png)
+
+#### Serving Your Own Website Data
+
+Now let's try serving a more interesting website. [Download the zipped
+files](https://github.com/gabrielecirulli/2048/archive/master.zip) for 2048, a
+popular (and addictive) web-based tile game. Extract this zip file into the
+folder you just opened:
+
+![Website files for 2048](../assets/nginx-2048-files.png)
+
+Switch back to Kitematic and restart the container by clicking the "Restart"
+button as shown below. Your Nginx container should now be serving 2048.
+
+![Nginx running 2048](../assets/nginx-serving-2048.png)
+
+**What just happened?**
+
+Kitematic can map Docker container volumes to directories on your
+Mac. In this case you changed the container's volume data via the Finder to
+serve a website we downloaded.
+
+## Next Steps
+
+For an example using Kitematic to run a Local RethinkDB database, take a look at
+the [RethinkDB development Database](./rethinkdb-dev-database.md) example.

docs/rethinkdb-dev-database.md

@@ -0,0 +1,61 @@
+page_title: Kitematic Tutorial: Set up an Nginx web server
+page_description: Tutorial demonstrating the setup of an Nginx web server using Docker and Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui, rethink, tutorial
+
+# Creating a Local RethinkDB Database for Development
+
+In this tutorial, you will:
+
+- Create a RethinkDB Container for Development
+- (Advanced) Clone a small Node.js application and write data into RethinkDB.
+
+### Setting up RethinkDB in Kitematic
+
+First, if you haven't yet done so, [download and start
+Kitematic](./index.md). Once open, the app should look like
+this:
+
+![Rethink create button](../assets/rethink-create.png)
+
+Click on the _Create_ button of the `rethinkdb` image listing in the recommended
+list as shown above. This will download & run a RethinkDB container within a few
+minutes. Once it's done, you'll have a local RethinkDB database up and running.
+
+![Rethink container](../assets/rethink-container.png)
+
+Let's start using it to develop a node.js app. For now, let's figure out which
+IP address and port RethinkDB is listening on. To find out, click the `Settings`
+tab and then the `Ports` section:
+
+![Rethink create button](../assets/rethink-ports.png)
+
+You can see there that for RethinkDB port `28015`, the container is listening on
+host `192.168.99.100` and port `49154` (in this example - ports may be different
+for you). This means you can now reach RethinkDB via a client driver at
+`192.168.99.100:49154`. Again, this IP address may be different for you.
+
+### (Advanced) Saving Data into RethinkDB with a local Node.js App
+
+First, if you don't have it yet, [download and install
+Node.js](http://nodejs.org/).
+
+> **Note**: this example needs Xcode installed. We'll replace it with something
+> with fewer dependencies soon.
+
+Now, you'll create the RethinkDB example chat application running on your local
+OS X system to test drive your new containerized database.
+In your terminal, type:
+
+     $ export RDB_HOST=192.168.99.100 # replace with IP from above step
+     $ export RDB_PORT=49154 # replace with Port from above step
+     $ git clone https://github.com/rethinkdb/rethinkdb-example-nodejs-chat
+     $ cd rethinkdb-example-nodejs-chat
+     $ npm install
+     $ npm start
+
+Now, point your browser to `http://localhost:8000`. Congratulations, you've
+successfully used a RethinkDB container in Kitematic to build a real-time chat
+app. Happy coding!
+
+![Rethink app preview](../assets/rethinkdb-preview.png)
+

docs/userguide.md

@@ -0,0 +1,188 @@
+page_title: Kitematic User Guide: Intro & Overview
+page_description: Documentation that provides an overview of Kitematic and installation instructions
+page_keywords: docker, documentation, about, technology, kitematic, gui
+
+# Kitematic user guide
+
+## Overview
+
+Kitematic is an open source project built to simplify and streamline using
+Docker on a Mac or Windows (coming soon) PC. Kitematic automates the Docker
+installation and setup process and provides an intuitive graphical user
+interface (GUI) for running Docker containers.  Kitematic integrates with
+[Docker Machine](http://docs.docker.com/machine/) to provision a VirtualBox VM
+and install the Docker Engine locally on your machine.
+
+Once installed, the Kitematic GUI launches and from the home screen you will be
+presented with curated images that you can run instantly. You can search for any
+public images on Docker Hub from Kitematic just by typing in the search bar. 
+You can use the GUI to create, run and manage your containers just by clicking
+on buttons. Kitematic allows you to switch back and forth between the Docker CLI
+and the GUI.  Kitematic also automates advanced features such as managing ports
+and configuring volumes.  You can use Kitematic to change environment variables,
+stream logs, and single click terminal into your Docker container all from the
+GUI.
+
+First, if you haven't yet done so, [download and start
+Kitematic](./index.md).
+
+## Container list
+
+Kitematic lists all running and stopped containers on the left side, underneath
+the "New Container" link.
+
+The container list includes all containers, even those not started by Kitematic,
+giving you a quick over-view of the state of your Docker daemon.
+
+You can click on any container to view its logs (the output of the PID-0 process),
+restart, stop or exec `sh` in that container. See [Working with a
+container](#working-with-a-container) for more details.
+
+## Creating a new container
+
+The "New Container" page lets you search for and select from images on the Docker Hub.
+When you've found the image you want to run, you can click "Create" to pull, create,
+and run the container.
+
+![Nginx create](../assets/browse-images.png)
+
+## Working with a container
+
+If you select a non-running container, either stopped, or paused, you will be able to
+"Restart" or "Stop" the container using the icons. You can also view the entire PID-0
+output logs, and in the Settings section you can make changes which will be used if you
+"Restart" this container.
+
+By selecting a running container from the left list, you can see some state information
+for your container - either a preview of the HTML output for a container that has a web
+server, the PID-0 logs, and any container volumes that have been configured.
+
+![Redis container in Kitematic](../assets/cli-redis-container.png)
+
+The summary page will show different things depending on the image metadata. If
+port 80 is `EXPOSED`, then Kitematic assumes its a web page, and will show a preview
+of the site at `/`. If other ports are exposed, then it will show a list of those
+ports, and the Docker daemon IP and port they are mapped to. If there are any `VOLUMES`,
+then these will be shown. At minimum, the summary screen will show the PID-0 log output.
+
+### Viewing container logs
+
+You can view the entire PID-0 container log output either by cicking on the "Logs"
+preview image, or by clicking on the "Logs" tab.
+
+You can then scroll through the logs from the current running container. Note that
+if you make changes to the container Settings, then the container will be restarted,
+so will reset this log view.
+
+### Starting a terminal in a container
+
+The "Terminal" icon at the top of the container summary will `docker exec sh <your container>`.
+This will allow you to make quick changes, or to debug a problem. 
+
+> **Note**: Your execed `sh` process will not have the same environment settings
+> as the main PID-0 process and its children.
+
+### Managing Volumes
+
+You can choose to make all of a container's volumes mapped to directories on
+on your Mac by clicking on the folders in the "Edit Files" section of the
+container summary screen.
+
+This allows you to manage files in volumes via the Finder.
+Kitematic exposes a container's volume data under `~/Kitematic/<container's name>/`.
+Quick access to this folder (or directory) is available via the app:
+
+![Accessing the volumes directory](../assets/volumes-dir.png)
+
+> **Note**: When you "Enable all volumes to edit files in Finder", the Docker
+> container will be stopped, removed and re-created with the new `volumes`
+> flag.
+
+#### Changing Volume Directories
+
+Let's say you have an Nginx webserver running via Kitematic (using the
+`kitematic/hello-world-nginx` image on DockerHub). However, you don't want to
+use the default directory created for the website_files volume. Instead, you
+already have the HTML, Javascript, and CSS for your website under
+`~/workspace/website`.
+
+Navigate to the "Settings" tab of the container, and goto the "Volumes". This
+screen allows you to set the mappings individually.
+
+![screen shot 2015-02-28 at 2 48 01 pm](../assets/change-folder.png)
+
+> **Note**: When you "Change Folders", the Docker
+> container will be stopped, removed and re-created with the new `volumes`
+> flag.
+
+### Setting the container name
+
+By default, Kitematic sets the container name to the same as the image name (or
+with a `-<number>` if there are more than one.
+To simplify administration, or when using container linking or volumes, you may
+want to rename it.
+
+> **Note**: When you rename the container it will be stopped, removed and
+> re-created with the new name (due to the default volumes mapping).
+
+### Adding Environment variables
+
+Many images use environment variables to let you customise them. The "General"
+"Settings" tab allows you to add and modify the environment variables used to
+start a container.
+
+The list of Environment variables will show any that have been set on the image
+metadata - for example, using the `ENV` instruction in the Dockerfile.
+
+<TODO: image of the jenkins container>
+
+Wen you "Save" the changed environment variables, the container will be stopped
+removed and re-created.
+
+### Delete container
+
+On the "General" "Settings" tab, you can delete the container. Clicking "Delete
+Container" will also stop the container if necessary.
+
+You can also delete a container clicking the `X` icon in the container list.
+
+Kitematic will prompt you to confirm that you want to delete.
+
+#### List the exposed Ports and how to access them
+
+To see the complete list of exposed ports, go to "Settings" then "Ports". This
+page lists all the container ports exposed, and the IP address and host only
+network port that you can access use to access that container from your OS X
+system.
+
+## Docker Command-line Access
+
+You can interact with existing containers in Kitematic or create new containers
+via the Docker Command Line Interface (CLI). Any changes you make on the CLI are
+directly reflected in Kitematic.
+
+To open a terminal via Kitematic, just press whale button at the bottom left, as
+shown below:
+
+![CLI access button](../assets/cli-access-button.png)
+
+### Example: Creating a new Redis container
+
+Start by opening a Docker-CLI ready terminal by clicking the whale button as
+described above. Once the terminal opens, enter `docker run -d -P redis`. This
+will pull and run a new Redis container via the Docker CLI.
+
+![Docker CLI terminal window](../assets/cli-terminal.png)
+
+> **Note**: If you're creating containers from the commandline, use `docker run -d`
+> so that Kitematic can re-create the container when settings are changed via the
+> Kitematic user interface. containers started without `-d` will fail to re-start.
+
+Now, go back to Kitematic. The Redis container should now be visible.
+
+![Redis container in Kitematic](../assets/cli-redis-container.png)
+
+## Next Steps
+
+For an example using Kitematic to run a Minecraft server, take a look at
+the [Mincraft server](./minecraft-server.md) page.