From 6afbd3ee289e5a787483bd3e2335b992d98c24c8 Mon Sep 17 00:00:00 2001 From: Ben Firshman Date: Fri, 20 Feb 2015 14:50:49 +0000 Subject: [PATCH] Remove docs from readme and link to docs Signed-off-by: Ben Firshman --- README.md | 329 +----------------------------------------------------- 1 file changed, 2 insertions(+), 327 deletions(-) diff --git a/README.md b/README.md index 07e03bdaee..3c18ff1175 100644 --- a/README.md +++ b/README.md @@ -38,334 +38,9 @@ dev virtualbox Running tcp://192.168.99.108:2376 staging * digitalocean Running tcp://104.236.37.134:2376 ``` -Machine creates Docker hosts that are secure by default. The connection between the client and daemon is encrypted and authenticated using TLS security. To get the Docker arguments for a machine use the command: `docker-machine config ` i.e. `docker-machine config dev`. +## Installation and documentation -You can also get the commands to export environment variables to use with the Docker CLI: `docker-machine env ` i.e. `docker-machine env dev` to show or `$(docker-machine env dev)` to load in your environment. - -## Try it out - -Machine is still in its early stages. If you'd like to try out a preview build, [download it here](https://github.com/docker/machine/releases/latest). - -## Swarm - -Machine can create [Docker Swarm](https://github.com/docker/swarm) clusters. - -First, create a Swarm token. Optionally, you can use another discovery service. -See the Swarm docs for details. - -To create the token, first create a Machine. This example will use VirtualBox. - -``` -$ docker-machine create -d virtualbox local -``` - -Load the Machine configuration into your shell: - -``` -$ $(docker-machine env local) -``` -Then run generate the token using the Swarm Docker image: - -``` -$ docker run swarm create -1257e0f0bbb499b5cd04b4c9bdb2dab3 -``` -Once you have the token, you can create the cluster. - -### Swarm Master - -Create the Swarm master: - -`docker-machine create -d virtualbox --swarm --swarm-master --swarm-discovery token:// swarm-master` - -Replace `` with your random token. This will create the Swarm master. - -### Swarm Nodes - -Now, create more Swarm nodes: - -`docker-machine create -d virtualbox --swarm --swarm-discovery token:// swarm-node-00` - -You now have a Swarm cluster. To connect to the Swarm master, you can use `docker-machine env --swarm swarm-master` - -For example: - -``` -$ docker-machine env --swarm swarm-master -export DOCKER_TLS_VERIFY=yes -export DOCKER_CERT_PATH=/home/ehazlett/.docker/machines/.client -export DOCKER_HOST=tcp://192.168.99.100:3376 -``` - -You can load this into your environment using `$(docker-machine env --swarm swarm-master)`. - -Now you can use the Docker CLI to query: - -``` -$ docker info -Containers: 1 -Nodes: 1 - swarm-node-00: 192.168.99.101:2376 -``` - -## Drivers - -### VirtualBox - -Creates machines locally on [VirtualBox](https://www.virtualbox.org/). Requires VirtualBox to be installed. - -Options: - - - `--virtualbox-boot2docker-url`: The URL of the boot2docker image. Defaults to the latest available version. - - `--virtualbox-disk-size`: Size of disk for the host in MB. Default: `20000` - - `--virtualbox-memory`: Size of memory for the host in MB. Default: `1024` - -### Digital Ocean - -Creates machines on [Digital Ocean](https://www.digitalocean.com/). You need to create a personal access token under "Apps & API" in the Digital Ocean Control Panel and pass that to `docker-machine create` with the `--digitalocean-access-token` option. - -Options: - - - `--digitalocean-access-token`: Your personal access token for the Digital Ocean API. - - `--digitalocean-image`: The name of the Digital Ocean image to use. Default: `docker` - - `--digitalocean-region`: The region to create the droplet in. Default: `nyc3` - - `--digitalocean-size`: The size of the Digital Ocean driver. Default: `512mb` - -### Microsoft Azure - -Create machines on [Microsoft Azure](http://azure.microsoft.com/). - -You need to create a subscription with a cert. Run these commands: - - $ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem - $ openssl pkcs12 -export -out mycert.pfx -in mycert.pem -name "My Certificate" - $ openssl x509 -inform pem -in mycert.pem -outform der -out mycert.cer - -Go to the Azure portal, go to the "Settings" page, then "Manage Certificates" and upload `mycert.cer`. - -Grab your subscription ID from the portal, then run `docker-machine create` with these details: - - $ docker-machine create -d azure --azure-subscription-id="SUB_ID" --azure-subscription-cert="mycert.pem" - -Options: - - - `--azure-subscription-id`: **required** Your Azure subscription ID. - - `--azure-subscription-cert`: **required** Your Azure subscription cert. - - `--azure-docker-port`: Azure Docker port. Default '2376' - - `--azure-image`: Azure image name. Default is Ubuntu 14.04 LTS x64 [$AZURE_IMAGE] - - `--azure-location`: Azure location. Default is 'West US' [$AZURE_LOCATION] - - `--azure-name`: Azure cloud service name - - `--azure-password`: Azure user password - - `--azure-publish-settings-file`: Azure publish settings file [$AZURE_PUBLISH_SETTINGS_FILE] - - `--azure-size`: Azure size. Default 'Small' [$AZURE_SIZE] - - `--azure-ssh-port`: Azure SSH port. Default '22' - - `--azure-username`: Azure username. Default 'ubuntu' - -Note: the machine name will be used as DNS name for the Cloud Service (e.g. machinename.cloudapp.net) and needs to be unique within Azure. - -### Amazon EC2 - -Create machines on [Amazon Web Services](http://aws.amazon.com). You will need an Access Key ID, Secret Access Key and a VPC ID. To find the VPC ID, login to the AWS console and go to Services -> VPC -> Your VPCs. Select the one where you would like to launch the instance. - -Options: - - - `--amazonec2-access-key`: **required** Your access key id for the Amazon Web Services API. - - `--amazonec2-ami`: The AMI ID of the instance to use Default: `ami-4ae27e22` - - `--amazonec2-instance-type`: The instance type to run. Default: `t2.micro` - - `--amazonec2-region`: The region to use when launching the instance. Default: `us-east-1` - - `--amazonec2-root-size`: The root disk size of the instance (in GB). Default: `16` - - `--amazonec2-secret-key`: **required** Your secret access key for the Amazon Web Services API. - - `--amazonec2-security-group-name`: AWS VPC security group name. Default: `docker-machine` - - `--amazonec2-session-token`: Your session token for the Amazon Web Services API. - - `--amazonec2-subnet-id`: AWS VPC subnet id - - `--amazonec2-vpc-id`: **required** Your VPC ID to launch the instance in. - - `--amazonec2-zone`: The AWS zone launch the instance in (i.e. one of a,b,c,d,e). Default: `a` - -### Google Compute Engine - -Create machines on [Google Compute Engine](https://cloud.google.com/compute/). You will need a Google account and project name. See https://cloud.google.com/compute/docs/projects for details on projects. - -The Google driver uses oAuth. When creating the machine, you will have your browser opened to authorize. Once authorized, paste the code given in the prompt to launch the instance. - -Options: - - - `--google-zone`: The zone to launch the instance. Default: `us-central1-a` - - `--google-machine-type`: The type of instance. Default: `f1-micro` - - `--google-disk-size`: The disk size of the instance (in GB). Default: `10` - - `--google-username`: The username to use for the instance. Default: `docker-user` - - `--google-instance-name`: The name of the instance. Default: `docker-machine` - - `--google-project`: The name of your project to use when launching the instance. - - `--google-scopes`: The scopes associated to the instance. Comma-separated if multiple scopes. Default: `https://www.googleapis.com/auth/devstorage.read_only,https://www.googleapis.com/auth/logging.write`` - -### VMware Fusion - -Creates machines locally on [VMware Fusion](http://www.vmware.com/products/fusion). Requires VMware Fusion to be installed. - -Options: - - - `--vmwarefusion-boot2docker-url`: URL for boot2docker image. - - `--vmwarefusion-disk-size`: Size of disk for host VM (in MB). Default: `20000` - - `--vmwarefusion-memory-size`: Size of memory for host VM (in MB). Default: `1024` - -### VMware vCloud Air - -Creates machines on [vCloud Air](http://vcloud.vmware.com) subscription service. You need an account within an existing subscription of vCloud Air VPC or Dedicated Cloud. - -Options: - - - `--vmwarevcloudair-username`: vCloud Air Username. - - `--vmwarevcloudair-password`: vCloud Air Password. - - `--vmwarevcloudair-catalog`: Catalog. Default: `Public Catalog` - - `--vmwarevcloudair-catalogitem`: Catalog Item. Default: `Ubuntu Server 12.04 LTS (amd64 20140927)` - - `--vmwarevcloudair-computeid`: Compute ID (if using Dedicated Cloud). - - `--vmwarevcloudair-cpu-count`: VM Cpu Count. Default: `1` - - `--vmwarevcloudair-docker-port`: Docker port. Default: `2376` - - `--vmwarevcloudair-edgegateway`: Organization Edge Gateway. Default: `` - - `--vmwarevcloudair-memory-size`: VM Memory Size in MB. Default: `2048` - - `--vmwarevcloudair-name`: vApp Name. Default: `` - - `--vmwarevcloudair-orgvdcnetwork`: Organization VDC Network to attach. Default: `-default-routed` - - `--vmwarevcloudair-provision`: Install Docker binaries. Default: `true` - - `--vmwarevcloudair-publicip`: Org Public IP to use. - - `--vmwarevcloudair-ssh-port`: SSH port. Default: `22` - - `--vmwarevcloudair-vdcid`: Virtual Data Center ID. - -### VMware vSphere - -Creates machines on a [VMware vSphere](http://www.vmware.com/products/vsphere) Virtual Infrastructure. Requires a working vSphere (ESXi and optionally vCenter) installation. The vSphere driver depends on [`govc`](https://github.com/vmware/govmomi/tree/master/govc) (must be in path) and has been tested with [vmware/govmomi@`c848630`](https://github.com/vmware/govmomi/commit/c8486300bfe19427e4f3226e3b3eac067717ef17). - -Options: - - - `--vmwarevsphere-username`: vSphere Username. - - `--vmwarevsphere-password`: vSphere Password. - - `--vmwarevsphere-boot2docker-url`: URL for boot2docker image. - - `--vmwarevsphere-compute-ip`: Compute host IP where the Docker VM will be instantiated. - - `--vmwarevsphere-cpu-count`: CPU number for Docker VM. Default: `2` - - `--vmwarevsphere-datacenter`: Datacenter for Docker VM (must be set to `ha-datacenter` when connecting to a single host). - - `--vmwarevsphere-datastore`: Datastore for Docker VM. - - `--vmwarevsphere-disk-size`: Size of disk for Docker VM (in MB). Default: `20000` - - `--vmwarevsphere-memory-size`: Size of memory for Docker VM (in MB). Default: `2048` - - `--vmwarevsphere-network`: Network where the Docker VM will be attached. - - `--vmwarevsphere-pool`: Resource pool for Docker VM. - - `--vmwarevsphere-vcenter`: IP/hostname for vCenter (or ESXi if connecting directly to a single host). - -### OpenStack - -Create machines on [Openstack](http://www.openstack.org/software/) - -Mandatory: - - - `--openstack-flavor-id`: The flavor ID to use when creating the machine - - `--openstack-image-id`: The image ID to use when creating the machine. - -Options: - - - `--openstack-auth-url`: Keystone service base URL. - - `--openstack-username`: User identifer to authenticate with. - - `--openstack-password`: User password. It can be omitted if the standard environment variable `OS_PASSWORD` is set. - - `--openstack-tenant-name` or `--openstack-tenant-id`: Identify the tenant in which the machine will be created. - - `--openstack-region`: The region to work on. Can be omitted if there is ony one region on the OpenStack. - - `--openstack-endpoint-type`: Endpoint type can be `internalURL`, `adminURL` or `publicURL`. It is a helper for the driver - to choose the right URL in the OpenStack service catalog. If not provided the default is `publicURL`. - - `--openstack-net-id`: The private network id the machine will be connected on. If your OpenStack project - contains only one private network it will be use automatically. - - `--openstack-sec-groups`: If security groups are available on your OpenStack you can specify a comma separated list - to use for the machine (e.g. `secgrp001,secgrp002`). - - `--openstack-floatingip-pool`: The IP pool that will be used to get a public IP and assign it to the machine. If there is an - IP address already allocated but not assigned to any machine, this IP will be chosen and assigned to the machine. If - there is no IP address already allocated a new IP will be allocated and assigned to the machine. - - `--openstack-ssh-user`: The username to use for SSH into the machine. If not provided `root` will be used. - - `--openstack-ssh-port`: Customize the SSH port if the SSH server on the machine does not listen on the default port. - -Environment variables: - -Here comes the list of the supported variables with the corresponding options. If both environment variable -and CLI option are provided the CLI option takes the precedence. - -| Environment variable | CLI option | -|----------------------|-----------------------------| -| `OS_AUTH_URL` | `--openstack-auth-url` | -| `OS_USERNAME` | `--openstack-username` | -| `OS_PASSWORD` | `--openstack-password` | -| `OS_TENANT_NAME` | `--openstack-tenant-name` | -| `OS_TENANT_ID` | `--openstack-tenant-id` | -| `OS_REGION_NAME` | `--openstack-region` | -| `OS_ENDPOINT_TYPE` | `--openstack-endpoint-type` | - -### Rackspace - -Create machines on [Rackspace cloud](http://www.rackspace.com/cloud) - -Options: - - - `--rackspace-username`: Rackspace account username - - `--rackspace-api-key`: Rackspace API key - - `--rackspace-region`: Rackspace region name - - `--rackspace-endpoint-type`: Rackspace endpoint type (adminURL, internalURL or the default publicURL) - - `--rackspace-image-id`: Rackspace image ID. Default: Ubuntu 14.10 (Utopic Unicorn) (PVHVM) - - `--rackspace-flavor-id`: Rackspace flavor ID. Default: General Purpose 1GB - - `--rackspace-ssh-user`: SSH user for the newly booted machine. Set to root by default - - `--rackspace-ssh-port`: SSH port for the newly booted machine. Set to 22 by default - -Environment variables: - -Here comes the list of the supported variables with the corresponding options. If both environment -variable and CLI option are provided the CLI option takes the precedence. - -| Environment variable | CLI option | -|----------------------|-----------------------------| -| `OS_USERNAME` | `--rackspace-username` | -| `OS_API_KEY` | `--rackspace-ap-key` | -| `OS_REGION_NAME` | `--rackspace-region` | -| `OS_ENDPOINT_TYPE` | `--rackspace-endpoint-type` | - -### Softlayer - -Create machines on [Softlayer](http://softlayer.com). - -You need to generate an API key in the softlayer control panel. -[Retrieve your API key](http://knowledgelayer.softlayer.com/procedure/retrieve-your-api-key) - -Options: - - `--softlayer-api-endpoint=`: Change softlayer API endpoint - - `--softlayer-user`: **required** username for your softlayer account, api key needs to match this user. - - `--softlayer-api-key`: **required** API key for your user account - - `--softlayer-cpu`: Number of CPU's for the machine. - - `--softlayer-disk-size: Size of the disk in MB. `0` sets the softlayer default. - - `--softlayer-domain`: **required** domain name for the machine - - `--softlayer-hostname`: hostname for the machine - - `--softlayer-hourly-billing`: Sets the hourly billing flag (default), otherwise uses monthly billing - - `--softlayer-image`: OS Image to use - - `--softlayer-local-disk`: Use local machine disk instead of softlayer SAN. - - `--softlayer-memory`: Memory for host in MB - - `--softlayer-private-net-only`: Disable public networking - - `--softlayer-region`: softlayer region - -### Hyper-V - -Creates a Boot2Docker virtual machine locally on your Windows machine -using Hyper-V. [See here](http://windows.microsoft.com/en-us/windows-8/hyper-v-run-virtual-machines) -for instructions to enable Hyper-V. You will need to use an -Administrator level account to create and manage Hyper-V machines. - -> **Note**: You will need an existing virtual switch to use the -> driver. Hyper-V can share an external network interface (aka -> bridging), see [this blog](http://blogs.technet.com/b/canitpro/archive/2014/03/11/step-by-step-enabling-hyper-v-for-use-on-windows-8-1.aspx). -> If you would like to use NAT, create an internal network, and use -> [Internet Connection -> Sharing](http://www.packet6.com/allowing-windows-8-1-hyper-v-vm-to-work-with-wifi/). - -Options: - - - `--hyper-v-boot2docker-location`: Location of a local boot2docker iso to use. Overrides the URL option below. - - `--hyper-v-boot2docker-url`: The URL of the boot2docker iso. Defaults to the latest available version. - - `--hyper-v-disk-size`: Size of disk for the host in MB. Defaults to `20000`. - - `--hyper-v-memory`: Size of memory for the host in MB. Defaults to `1024`. The machine is setup to use dynamic memory. - - `--hyper-v-virtual-switch`: Name of the virtual switch to use. Defaults to first found. - -## Running on Windows -Machine needs some helper applications to be installed (`ssh`, etc). The easiest way to get started on Windows -is to install [msysGit](https://msysgit.github.io/) and [OpenSSL on Windows](http://slproweb.com/products/Win32OpenSSL.html). -After this, you should have a working setup to use Machine. +Full documentation [is available here](https://docs.docker.com/machine/). ## Contributing