Docker Dream Land

README.md

Docker Dream Land

This document describes an idealized version of what a dream development environment that uses Docker looks like based on my own experience.

What it looks like for a dev joining an existing project

Below describes what working on a Dockerized project looks like to a dev starting with that project for the first time.

Ideally, a README for a particular project will, at the bare minimum, have a similar layout:

1. Prerequisites: Links to how to set up Docker... anything else the project requires a dev to do first (hopefully nothing)

2. Getting Started / Installation: How to spin up the service, other high level information knowing within the first hour of working on a thing.

3. Running Tests

4. Other common tasks and how to accomplish them

Aside Contribution Guidelines are tangentially, but equally important in a README.

Prerequisites

Installing the whole Docker toolchain (specifically, Docker Engine, Docker Machine, and Docker Compose are required for local development).

Ideally, one document describes getting started and all repo READMEs point to that document. Very ideally, that document would be Docker's own docs.

Getting started

1. Clone the repo:

git clone [my-cool-git-repo]

2. Copy example configs to get up-to-date config stuff.

3. Run docker-compose up This will build a new Docker image from ./Dockerfile to run this repo, and pulls down all services this project relies on from a private Docker registry and runs them.

Running tests

Run docker-compose run [container-name] [my-cool-test-running-command]

Other tasks

Anything else you need to do (asset compilation, database migrations, etc, etc) just involves running docker-compose run [container-name] [command].

These should be well documented.

What it requires from the repo maintainers

Good documentation

A passable README should, at least, include:

1. What the project is and why it exists

2. Information about any prerequisites to get the project running

3. Installation instructions

4. A "Getting Started" section detailing high-level information about the service you would want someone to know if they just walked in the door of Emma knowing nothing else.

5. Information about how to run tests

6. Information about other tasks / scripts that someone might want to do / run.

7. Contribution guidelines

8. How to submit an issue

9. Details about the build / deployment pipeline

10. Links to further resources about the project (i.e. link to a wiki, links to docs for software the project relies on, hints on where in the code to look first when reading the code for the first or second time, issue tracker, etc.)

Ideally, your README will also include a table of contents somewhere near the top. There are good tools for automating the table of contents like doctoc.

If any of these sections make your README unwieldy it's recommended you move that section into its own document, either in a docs directory in your project or on a wiki and link to it in the README. Wherever your document lives make sure it's somewhere where contributors can easily collaborate. This is why in version control or a wiki is a really good choice.

A thorough understanding of Docker

If you've never used docker, start here.

If you've used docker level up on best practices with Docker's own documentation on best practices for writing Dockerfiles.

Make sure you understand how to effectively use docker-compose.

Service discovery implementation

Consul seems to be the de facto choice. Fantastic documentation on what this looks like for local environments can be found here.

A Dockerfile in the root of your project

Again, refer to Docker's best practice. Also, note that there should be steps to register the service with consul to enable service discovery.

A docker-compose.yml in the root of your project

You'll use it alot).

Good documentation

This is here twice on purpose. It's really important.

Level up your documentation game reading some of these articles:

Beginner's Guide to Docs

10 Things You Can Do To Create Better Documentation

Read some beautiful docs to get inspired:

List of Beautiful Docs

Read some good books!

Strunk & White's Elements of Style

On Writing Well

Technical Writing 101

The Insider's Guide to Technical Writing

Docker Registry

If you're working at a company with closed-source / proprietary software you're going to have an additional challenge of where to host Docker images.

There are basically two options:

1. Pay Docker to do it. This is basically equivalent paying for private git repos on Github. They also have an option where they'll host a private registry for you.

2. Host your own registry.