Initial port of KM docs

WIP. Do not publish without proofing and testing.

docs/faq.md

@@ -0,0 +1,47 @@
+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.

docs/index.md

@@ -0,0 +1,43 @@
+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
+
+# Welcome to Kitematic
+
+## 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.
+
+## 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](/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.

docs/known-issues.md

@@ -0,0 +1,29 @@
+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/managing-volumes.md

@@ -0,0 +1,19 @@
+page_title: Managing Volumes with Kitematic
+page_description: Documentation explaining how Kitematic manages container volumes
+page_keywords: docker, documentation, about, technology, kitematic, gui, volumes
+
+
+# Managing Volumes
+
+
+### Default Volume Directories
+
+Every container created through Kitematic automatically has its volumes exposed on your Mac, which means you can 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)
+
+### 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`. Kitematic makes it easy to change the container's volume to read from this directory instead of the default one created by Kitematic:
+
+![screen shot 2015-02-28 at 2 48 01 pm](/assets/change-folder.png)

docs/minecraft-server.md

@@ -0,0 +1,53 @@
+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
+
+Create a container from the recommended Minecraft image by clicking the "Create" button.
+
+![create Minecraft container](/assets/minecrafte-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. 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.
+
+

docs/nginx-web-server.md

@@ -0,0 +1,54 @@
+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](https://kitematic.com/download) . 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. This will download and run a tiny Nginx web server in a container via Kitematic, allowing you to serve website data on 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:
+
+![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 automatically reveals Docker container volumes via directories on your Mac. In this case you changed the container's volume data via the Finder to serve a website we downloaded.

docs/rethinkdb-dev-database.md

@@ -0,0 +1,47 @@
+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](https://kitematic.com/download). 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-create.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/).
+
+Now, you'll create the RethinkDB example chat to test drive your new database. In your terminal, type:
+
+     bash-3.2$ export RDB_HOST=192.168.99.100 # replace with IP from above step
+     bash-3.2$ export RDB_PORT=49154 # replace with Port from above step
+     bash-3.2$ git clone https://github.com/rethinkdb/rethinkdb-example-nodejs-chat
+     bash-3.2$ cd rethinkdb-example-nodejs-chat
+     bash-3.2$ npm install
+     bash-3.2$ 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/rethink-preview.png)
+

docs/using-docker-cli.md

@@ -0,0 +1,25 @@
+page_title: Accessing the Docker CLI in Kitematic
+page_description: Documentation describing how to work on the Docker command line using Kitematic
+page_keywords: docker, documentation, about, technology, kitematic, gui, cli, 
+
+
+# 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.
+
+
+### Opening a Terminal for the Docker CLI
+
+To open a terminal via Kitematic, just press whale button at the bottom left, as shown below:
+
+![CLI access button](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](cli-terminal.png)
+
+Now, go back to Kitematic. The Redis container should now be visible.
+
+![Redis container in Kitematic](cli-redis-container.png)