github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/docs/installation/cloud-ex-machine-ocean.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Example: Use Docker Machine to provision cloud hosts"
     4  description = "Example of using Docker Machine to install Docker Engine on a cloud provider, using Digital Ocean."
     5  keywords = ["cloud, docker, machine, documentation,  installation, digitalocean"]
     6  [menu.main]
     7  parent = "smn_cloud"
     8  +++
     9  <![end-metadata]-->
    10  
    11  # Example: Use Docker Machine to provision cloud hosts
    12  
    13  Docker Machine driver plugins are available for many cloud platforms, so you can use Machine to provision cloud hosts. When you use Docker Machine for provisioning, you create cloud hosts with Docker Engine installed on them.
    14  
    15  You'll need to install and run Docker Machine, and create an account with the cloud provider.
    16  
    17  Then you provide account verification, security credentials, and configuration options for the providers as flags to `docker-machine create`. The flags are unique for each cloud-specific driver.  For instance, to pass a Digital Ocean access token you use the `--digitalocean-access-token` flag.
    18  
    19  As an example, let's take a look at how to create a Dockerized <a href="https://digitalocean.com" target="_blank">Digital Ocean</a> _Droplet_ (cloud server).
    20  
    21  ### Step 1. Create a Digital Ocean account and log in
    22  
    23  If you have not done so already, go to <a href="https://digitalocean.com" target="_blank">Digital Ocean</a>, create an account, and log in.
    24  
    25  ### Step 2. Generate a personal access token
    26  
    27  To generate your access token:
    28  
    29    1. Go to the Digital Ocean administrator console and click **API** in the header.
    30  
    31      ![Click API in Digital Ocean console](images/ocean_click_api.png)
    32  
    33    2. Click **Generate New Token** to get to the token generator.
    34  
    35      ![Generate token](images/ocean_gen_token.png)
    36  
    37    3. Give the token a clever name (e.g. "machine"), make sure the **Write (Optional)** checkbox is checked, and click **Generate Token**.
    38  
    39      ![Name and generate token](images/ocean_token_create.png)
    40  
    41    4. Grab (copy to clipboard) the generated big long hex string and store it somewhere safe.
    42  
    43      ![Copy and save personal access token](images/ocean_save_token.png)
    44  
    45      This is the personal access token you'll use in the next step to create your cloud server.
    46  
    47  ### Step 3. Start Docker Machine
    48  
    49  1. If you have not done so already, install Docker Machine on your local host.
    50  
    51    * <a href="https://docs.docker.com/engine/installation/mac/" target="_blank"> How to install Docker Machine on Mac OS X</a>
    52  
    53    * <a href="https://docs.docker.com/engine/installation/windows/" target="_blank">How to install Docker Machine on Windows</a>
    54  
    55    * <a href="https://docs.docker.com/machine/install-machine/" target="_blank">Install Docker Machine directly</a> (e.g., on Linux)
    56  
    57  2. At a command terminal, use `docker-machine ls` to get a list of Docker Machines and their status.
    58  
    59          $ docker-machine ls
    60          NAME      ACTIVE   DRIVER       STATE     URL   SWARM
    61          default   -        virtualbox   Stopped    
    62  
    63  3. If Machine is stopped, start it.
    64  
    65          $ docker-machine start default
    66          (default) OUT | Starting VM...
    67          Started machines may have new IP addresses. You may need to re-run the `docker-machine env` command.
    68  
    69  4. Set environment variables to connect your shell to the local VM.
    70  
    71          $ docker-machine env default
    72          export DOCKER_TLS_VERIFY="1"
    73          export DOCKER_HOST="tcp://xxx.xxx.xx.xxx:xxxx"
    74          export  DOCKER_CERT_PATH="/Users/londoncalling/.docker/machine/machines/default"
    75          export DOCKER_MACHINE_NAME="default"
    76          # Run this command to configure your shell:
    77          # eval "$(docker-machine env default)"
    78  
    79          eval "$(docker-machine env default)"
    80  
    81  5. Re-run `docker-machine ls` to check that it's now running.
    82  
    83          $ docker-machine ls
    84          NAME      ACTIVE   DRIVER       STATE     URL                         SWARM
    85          default   *        virtualbox   Running   tcp:////xxx.xxx.xx.xxx:xxxx  
    86  
    87  6. Run some Docker commands to make sure that Docker Engine is also up-and-running.
    88  
    89      We'll run `docker run hello-world` again, but you could try `docker ps`,  `docker run docker/whalesay cowsay boo`, or another command to verify that Docker is running.
    90  
    91          $ docker run hello-world
    92  
    93          Hello from Docker.
    94          This message shows that your installation appears to be working correctly.
    95  
    96          To generate this message, Docker took the following steps:
    97          1. The Docker client contacted the Docker daemon.
    98          2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    99          3. The Docker daemon created a new container from that image which runs the executable that produces the output you are currently reading.
   100          4. The Docker daemon streamed that output to the Docker client, which sent it to your terminal.
   101  
   102          To try something more ambitious, you can run an Ubuntu container with:
   103          $ docker run -it ubuntu bash
   104  
   105          Share images, automate workflows, and more with a free Docker Hub account: https://hub.docker.com
   106  
   107          For more examples and ideas, visit:
   108          https://docs.docker.com/userguide/
   109  
   110  ### Step 4. Use Docker Machine to Create the Droplet
   111  
   112  1. Run `docker-machine create` with the `digitalocean` driver and pass your key to the `--digitalocean-access-token` flag, along with a name for the new cloud server.
   113  
   114      For this example, we'll call our new Droplet "docker-sandbox".
   115  
   116          $ docker-machine create --driver digitalocean --digitalocean-access-token 455275108641c7716462d6f35d08b76b246b6b6151a816cf75de63c5ef918872 docker-sandbox
   117          Running pre-create checks...
   118          Creating machine...
   119          (docker-sandbox) OUT | Creating SSH key...
   120          (docker-sandbox) OUT | Creating Digital Ocean droplet...
   121          (docker-sandbox) OUT | Waiting for IP address to be assigned to the Droplet...
   122          Waiting for machine to be running, this may take a few minutes...
   123          Machine is running, waiting for SSH to be available...
   124          Detecting operating system of created instance...
   125          Detecting the provisioner...
   126          Provisioning created instance...
   127          Copying certs to the local machine directory...
   128          Copying certs to the remote machine...
   129          Setting Docker configuration on the remote daemon...
   130          To see how to connect Docker to this machine, run: docker-machine env docker-sandbox
   131  
   132        When the Droplet is created, Docker generates a unique SSH key and stores it on your local system in `~/.docker/machines`. Initially, this is used to provision the host. Later, it's used under the hood to access the Droplet directly with the `docker-machine ssh` command. Docker Engine is installed on the cloud server and the daemon is configured to accept remote connections over TCP using TLS for authentication.
   133  
   134  2. Go to the Digital Ocean console to view the new Droplet.
   135  
   136      ![Droplet in Digital Ocean created with Machine](images/ocean_droplet.png)
   137  
   138  3. At the command terminal, run `docker-machine ls`.
   139  
   140          $ docker-machine ls
   141          NAME             ACTIVE   DRIVER         STATE     URL                         SWARM
   142          default          *        virtualbox     Running   tcp://192.168.99.100:2376   
   143          docker-sandbox   -        digitalocean   Running   tcp://45.55.139.48:2376     
   144  
   145      Notice that the new cloud server is running but is not the active host. Our command shell is still connected to the default machine, which is currently the active host as indicated by the asterisk (*).
   146  
   147  4. Run `docker-machine env docker-sandbox` to get the environment commands for the new remote host, then run `eval` as directed to re-configure the shell to connect to `docker-sandbox`.
   148  
   149          $ docker-machine env docker-sandbox
   150          export DOCKER_TLS_VERIFY="1"
   151          export DOCKER_HOST="tcp://45.55.222.72:2376"
   152          export DOCKER_CERT_PATH="/Users/victoriabialas/.docker/machine/machines/docker-sandbox"
   153          export DOCKER_MACHINE_NAME="docker-sandbox"
   154          # Run this command to configure your shell:
   155          # eval "$(docker-machine env docker-sandbox)"
   156  
   157          $ eval "$(docker-machine env docker-sandbox)"
   158  
   159  5. Re-run `docker-machine ls` to verify that our new server is the active machine, as indicated by the asterisk (*) in the ACTIVE column.
   160  
   161          $ docker-machine ls
   162          NAME             ACTIVE   DRIVER         STATE     URL                         SWARM
   163          default          -        virtualbox     Running   tcp://192.168.99.100:2376   
   164          docker-sandbox   *        digitalocean   Running   tcp://45.55.222.72:2376     
   165  
   166  6. Log in to the Droplet with the `docker-machine ssh` command.
   167  
   168          $ docker-machine ssh docker-sandbox
   169          Welcome to Ubuntu 14.04.3 LTS (GNU/Linux 3.13.0-71-generic x86_64)
   170  
   171          * Documentation:  https://help.ubuntu.com/
   172  
   173          System information as of Mon Dec 21 21:38:53 EST 2015
   174  
   175          System load:  0.77               Processes:              70
   176          Usage of /:   11.4% of 19.56GB   Users logged in:        0
   177          Memory usage: 15%                IP address for eth0:    45.55.139.48
   178          Swap usage:   0%                 IP address for docker0: 172.17.0.1
   179  
   180          Graph this data and manage this system at:
   181          https://landscape.canonical.com/
   182  
   183  7. Verify Docker Engine is installed correctly by running `docker run hello-world`.
   184  
   185            ubuntu@ip-172-31-0-151:~$ sudo docker run hello-world
   186            Unable to find image 'hello-world:latest' locally
   187            latest: Pulling from library/hello-world
   188            b901d36b6f2f: Pull complete
   189            0a6ba66e537a: Pull complete
   190            Digest: sha256:8be990ef2aeb16dbcb9271ddfe2610fa6658d13f6dfb8bc72074cc1ca36966a7
   191            Status: Downloaded newer image for hello-world:latest
   192  
   193            Hello from Docker.
   194            This message shows that your installation appears to be working correctly.
   195            . . .
   196  
   197        You can type keyboard command Control-D or `exit` to log out of the remote server.
   198  
   199  #### Understand the defaults and options on the create command
   200  
   201  For convenience, `docker-machine` will use sensible defaults for choosing settings such as the image that the server is based on, but you override the defaults using the respective flags (e.g. `--digitalocean-image`). This is useful if, for example, you want to create a cloud server with a lot of memory and CPUs (by default `docker-machine` creates a small server). For a full list of the flags/settings available and their defaults, see the output of `docker-machine create -h` at the command line. See also <a href="https://docs.docker.com/machine/drivers/os-base/" target="_blank">Driver options and operating system defaults</a> and information about the <a href="https://docs.docker.com/machine/reference/create/" target="_blank">create</a> command in the Docker Machine documentation.
   202  
   203  
   204  ### Step 5. Use Docker Machine to remove the Droplet
   205  
   206  To remove a host and all of its containers and images, first stop the machine, then use `docker-machine rm`:
   207  
   208      $ docker-machine stop docker-sandbox
   209      $ docker-machine rm docker-sandbox
   210      Do you really want to remove "docker-sandbox"? (y/n): y
   211      Successfully removed docker-sandbox
   212  
   213      $ docker-machine ls
   214      NAME      ACTIVE   DRIVER       STATE     URL                         SWARM
   215      default   *        virtualbox   Running   tcp:////xxx.xxx.xx.xxx:xxxx
   216  
   217  If you monitor the Digital Ocean console while you run these commands, you will see it update first to reflect that the Droplet was stopped, and then removed.
   218  
   219  If you create a host with Docker Machine, but remove it through the cloud provider console, Machine will lose track of the server status. So please use the `docker-machine rm` command for hosts you create with `docker-machine --create`.
   220  
   221  ## Where to go next
   222  
   223  * To learn more about options for installing Docker Engine on cloud providers, see [Understand cloud install options and choose one](cloud.md).
   224  
   225  * To learn more about using Docker Machine to provision cloud hosts, see <a href="https://docs.docker.com/machine/get-started-cloud/" target="_blank">Using Docker Machine with a cloud provider</a>.
   226  
   227  * To get started with Docker, see <a href="https://docs.docker.com/engine/userguide/" target="_blank"> Docker User Guide</a>.