dev

README

dev

dev is a command line tool that wraps Docker Compose to enable shared resources for an ideal development environment.

Background

Requirements

• Support sharing of docker-compose configuration across projects
• Support sharing of networks across projects (i.e., manage creation of 'external' networks directly)
• Support authentication with private container repositories
• Support dependencies between projects, networks and registries

Table of Contents

• Installing
• Overview
• Commands
  • build
  • up
  • ps
  • sh

Installing

Binaries available for linux and and osx here.

Contributing

You will need a current version of golang that supports modules to build this project.

Configuration

Dev will search the current directory and its parent directory until it locates a configuration file. The name of the configuration is .dev.yaml but can be overridden with the --config flag. If a per-project configuration file cannot be found, dev will look in your home directory and finally in $XDG_CONFIG_HOME/dev for one.

If a configuration file is not found, dev will look in the current working directory for a docker-compose.yml file. If one is found, it will create a dev project with the base name of current directory. For example, if you are located in $HOME/Projects/my-app and there is a docker-compose.yml in that directory, dev will create a command named 'my-app' and a number of subcommands. These subcommands can be listed by running dev my-app --help.

If you require more than one docker-compose.yml for your project, you can specify these in the .dev.yaml file. For example, for the my-app project which has a layout like this:

  $HOME/Projects/my-app:
    .dev.yaml
    docker-compose.yml

  $HOME/Projects/my-app/docker
    docker-compose.shared.yml

The $HOME/Projects/my-app/dev.yml might contain something like this:

projects:
 my-app:
   docker_compose_files:
     - "docker/docker-compose.shared.yml"
     - "docker-compose.yml"
   depends_on: ["my-external-network"]

networks:
 my-external-network:
   driver: bridge
   ipam:
     driver: default
     config:
       - subnet: 173.16.242.0/16

Running 'dev my-app build' will provide both docker-compose.yml configuration files to docker-compose with the -f flag.

When 'dev my-app up' is run, "my-external-network" will be created if it does not exist.

Run 'dev my-app sh' to get a shell in the container or 'dev my-app sh ls -al' to run 'ls -al' in the project container. The "project" container is the container in the docker-compose.yml with the same name as the project in the .dev.yaml file.

Overview

Run dev to see a list of Projects

Project Commands

The following commands are sub-commands added to each project added to .dev.yaml. If no .dev.yaml could not be located, dev will look in the current directory for a docker-compose.yml file and add a project with the same name as the current directory.

build

Run docker-compose build for the specified project. The build will specify all the docker-compose files in the project's docker_compose_files array.

ps

View details about the services running for the specified project. This is the output of docker-compose ps for your project.

up

Start the containers for the specified project. This will build or fetch the images as required.

sh

Run without arguments this command runs an interactive shell on the project container. If run with arguments, the arguments are passed to the container shell with the -c flag.

If this command is run from a subdirectory of the project directory this command will first change directories such that relative commands from your directory on the host can be run. If run from outside of your project directory the starting directory defaults to the WORKDIR specified in the project's Dockerfile.

Documentation

Index

• Constants
• func InitDeps(appConfig *c.Dev, cmd string, project *Project) error
• func RunComposeBuild(project string, composePaths []string, args ...string)
• func RunComposeDown(project string, composePaths []string, args ...string)
• func RunComposeLogs(project string, composePaths []string, args ...string)
• func RunComposePs(project string, composePaths []string, args ...string)
• func RunComposeUp(project string, composePaths []string, args ...string)
• func RunOnContainer(containerName string, cmds ...string)
• func SliceContainsString(slice []string, a string) bool
• func SliceInsertString(s []string, str string, index int) []string
• type Dependency
• type Network
  • func NewNetwork(name string, config *types.NetworkCreate) *Network
  • func (n *Network) Dependencies() []string
  • func (n *Network) GetName() string
  • func (n *Network) PreRun(command string, appConfig *c.Dev, project *Project)
• type Project
  • func NewProject(config *c.Project) *Project
  • func (p *Project) Dependencies() []string
  • func (p *Project) GetName() string
  • func (p *Project) PreRun(command string, appConfig *c.Dev, project *Project)
  • func (p *Project) Shell(appConfig *c.Dev, args []string)
  • func (p *Project) Up(appConfig *c.Dev, followLogs bool)
• type Registry
  • func NewRegistry(config *c.Registry) *Registry
  • func (r *Registry) Dependencies() []string
  • func (r *Registry) GetName() string
  • func (r *Registry) PreRun(command string, appConfig *c.Dev, project *Project)

Constants

const (
	// BUILD constant referring to the build command of this project which
	// builds the project with docker-compose as specified in this tools
	// configuration file.
	BUILD = "build"
	// DOWN constant referring to the "down" command of this project which
	// stops and removes the project container.
	DOWN = "down"
	// PS constant referring to the "ps" command of this project which
	// shows the status of the containers used by the project.
	PS = "ps"
	// SH constant referring to the "sh" command of this project which runs
	// commands on the project container.
	SH = "sh"
	// UP constant referring to the "up" command of this project which
	// starts the project and any of the specified dependencies.
	UP = "up"
)

Functions

func InitDeps

func InitDeps(appConfig *c.Dev, cmd string, project *Project) error

InitDeps runs the PreRun method on each dependency for the specified Project.

func RunComposeBuild

func RunComposeBuild(project string, composePaths []string, args ...string)

RunComposeBuild runs docker-compose build with the specified docker compose files and args.

func RunComposeDown

func RunComposeDown(project string, composePaths []string, args ...string)

RunComposeDown runs docker-compose down with the specified docker compose files and args.

func RunComposeLogs

func RunComposeLogs(project string, composePaths []string, args ...string)

RunComposeLogs runs docker-compose logs with the specified docker compose files and args.

func RunComposePs

func RunComposePs(project string, composePaths []string, args ...string)

RunComposePs runs docker-compose ps with the specified docker compose files and args.

func RunComposeUp

func RunComposeUp(project string, composePaths []string, args ...string)

RunComposeUp runs docker-compose up with the specified docker compose files and args.

func RunOnContainer

func RunOnContainer(containerName string, cmds ...string)

RunOnContainer runs the commands on the container with the specified name using the 'docker' command.

func SliceContainsString

func SliceContainsString(slice []string, a string) bool

SliceContainsString checks the provided slice for the specified string and returns true if it was found, otherwise returns false.

func SliceInsertString

func SliceInsertString(s []string, str string, index int) []string

SliceInsertString inserts string at the specified index of the provided slice. From Slice Tricks.

Types

type Dependency

type Dependency interface {
	// PreRun does whatever is required of the dependency. It is run prior
	// to the specified command for the given project.
	PreRun(command string, appConfig *c.Dev, project *Project)
	// Dependencies returns the names of all the dev objects it depends on
	// in order to function.
	Dependencies() []string
	// Name of the depencency. Maps to the name given to the object in the
	// dev configuration file.
	GetName() string
}

Dependency is the interface that is used by all objects in the dev configuration implement such that they can be used as a dependency by other objects of the configuration.

type Network

type Network struct {
	Name   string
	Config *types.NetworkCreate
}

Network is an external docker network that dev manages.

func NewNetwork

func NewNetwork(name string, config *types.NetworkCreate) *Network

NewNetwork is the Network constructor.

func (*Network) Dependencies

func (n *Network) Dependencies() []string

Dependencies implements the Dependency interface. At this time a Network cannot have dependencies so it returns an empty slice.

func (*Network) GetName

func (n *Network) GetName() string

GetName returns the name of the network as named by the user in the configuration file.

func (*Network) PreRun

func (n *Network) PreRun(command string, appConfig *c.Dev, project *Project)

PreRun implements the Dependency interface. It will destroy any containers that are attached to a no longer existing network of the same name such that the containers can be created with the correct network.

type Project

type Project struct {
	Name   string
	Config *c.Project
}

Project is the group of functionality provided by a docker-compose file.

func NewProject

func NewProject(config *c.Project) *Project

NewProject is the Project constructor.

func (*Project) Dependencies

func (p *Project) Dependencies() []string

Dependencies implements the Depedency interface. It returns a list of the names of its dependencies. These can be names of other projects, networks or registries.

func (*Project) GetName

func (p *Project) GetName() string

GetName returns the name of the project as configured by the user in the dev configuration file.

func (*Project) PreRun

func (p *Project) PreRun(command string, appConfig *c.Dev, project *Project)

PreRun implements the Dependency interface. It brings up the project prior to the shell and up commads.

func (*Project) Shell

func (p *Project) Shell(appConfig *c.Dev, args []string)

Shell runs commands or creates an interfactive shell on the Project container.

func (*Project) Up

func (p *Project) Up(appConfig *c.Dev, followLogs bool)

Up brings up the specified project with its dependencies and optionally tails the logs of the project container.

type Registry

type Registry struct {
	Config *c.Registry
}

Registry is a private container registry that dev will attempt to login to so images can be pulled from it.

func NewRegistry

func NewRegistry(config *c.Registry) *Registry

NewRegistry constructs Registry objects.

func (*Registry) Dependencies

func (r *Registry) Dependencies() []string

Dependencies implements the Dependency interface.

func (*Registry) GetName

func (r *Registry) GetName() string

GetName returns the name of the registry as defined by the user in the dev configuration file.

func (*Registry) PreRun

func (r *Registry) PreRun(command string, appConfig *c.Dev, project *Project)

PreRun implements the Dependency interface.