Code examples#

Note

For more information about formatting code, see the “Code” row in the Text formatting topic.

Use the following guidelines when creating blocks of code as input or output examples:

  • Don’t use screenshots to show code examples. Format them as blocks of code by using the appropriate markup in your authoring tool. For more information about formatting, see Text formatting.

  • When showing input, always include a command prompt (such as $).

  • As often as necessary, show input and output in separate blocks and provide explanations for each. For example, if the input contains arguments or parameters, explain those. If the user should expect something specific in the output, or you want to show only part of lengthy output, provide an explanation.

  • When the command is simple, and there’s nothing specific to say about the output, you can show the input and output in the same code block, as users would actually see the code in their own terminal. The inclusion of the command prompt differentiates the input from the output.

  • Ensure that any placeholder text in code is obvious.

    • If the authoring tool allows it, apply italics to placeholders; if not, enclose them in angle brackets.

    • Use lowercase letters for single-word placeholders. To show multiple-word placeholders, don’t separate the words with spaces or symbols and capitalize the first letter of each word after the first word (camelCase).

      Note

      Use lowercase and camelCase unless you have to follow the conventions of the programming language. For example, you might need to use underscores (account_ID) or all capitals (ACCOUNT_ID).

  • Follow the conventions of the programming language used and preserve the capitalization that the author of the code used.

  • For readability, you can break up long lines of input into readable blocks by ending each line with a backslash.

  • If the input includes a list of arguments or parameters, show the important or relevant ones first, and group related ones. If no other order makes sense, use alphabetical order. If you explain the arguments or parameters in text, show them in the same order that they appear in the code block.

The following examples illustrate many of these guidelines:

Create a VM running a Docker host#

  1. Show all the available virtual machines (VMs) that are running Docker.

    $ docker-machine ls
    

    If you have not created any VMs yet, your output should look as follows:

    NAME ACTIVE DRIVER STATE URL
    
  2. Create a VM that’s running Docker.

    $ docker-machine create --driver virtualbox test
    

    The --driver flag indicates what type of driver the machine runs on. In this case, virtualbox indicates that the driver is Oracle VirtualBox. The final argument in the command gives the VM a name, in this case, test.

    The output should look as follows:

    Creating VirtualBox VM...
    Creating SSH key...
    Starting VirtualBox VM...
    Starting VM...
    To see how to connect Docker to this machine, run:
    docker-machine env test
    
  3. Run docker-machine ls again to see the VM that you created.

    The output should look as follows:

    NAME ACTIVE DRIVER STATE URL SWARM
    test virtualbox Running tcp://192.168.99.101:237
    

Run the application#

  1. Run a container from the image. The application code uses the environment variables that you defined to connect to the MongoDB container.

    $ docker run --detach \
      --env MONGO_HOST=$MONGO_HOST \ env MONGO_PORT=$MONGO_PORT \ env
      --MONGO_SSL=$MONGO_SSL \ env MONGO_DATABASE=$MONGO_DATABASE \ env
      --MONGO_USER=$MONGO_USER \ env MONGO_PASSWORD=$MONGO_PASSWORD \ publish
      --5000:5000 \
      guestbook-mongo:1.0
    
  2. View the status of the container by using the --latest parameter.

    $ docker ps --latest
    

The status of the container should begin with Up.

Remove the containers already using the port#

  1. To identify the containers that are using the port, run the following command, changing <port> to the port number that you want to use.

    $ docker ps -a | grep <port>/tcp
    
  2. To remove the containers, run the following command for each container identified in step 1, changing <containerId> to the ID of the container.

    The --force argument ensures that the container is removed even if it’s currently running.

    docker rm --force --volumes <containerId>
    

Troubleshooting#

Sometimes, when you use a docker command, you receive the following output:

$ docker info Get http:///var/run/docker.sock/v1.20/info: dial unix
/var/run/docker.sock: no such file or directory.
* Are you trying to connect to a TLS-enabled daemon without TLS?
* Is your docker daemon up and running?

If you receive this output, your VM isn’t running on a Docker host.