Lack of documentation - Githubissues

micaelgallego commented 7 years ago

Hi,

I'm very interested in execute docker-compose commands from Java code. I've found your repo and it is very interesting. Do you plan to publish some short of documentation of this repository? It is supposed to be a replacement of docker-compose CLI tool or a library to be used inside another Java program?

Thanks for that awesome work.

gesellix commented 7 years ago

Hi, thanks for your interest!

Due to lack of time I didn't have a chance to write any documentation, yet, and I fully agree that the source won't guide you very much to help you getting started. The library is kept very simple, though:

You might want to start with the ComposeFileReader to load a .yaml file. I personally use it in my docker-client library at https://github.com/gesellix/docker-client/blob/0ee342ef0d766c44909f83cb6fba720ed627fcc5/client/src/main/groovy/de/gesellix/docker/client/stack/DeployConfigReader.groovy#L54

My focus was to load Docker Stack .yaml files, which are working with the v3 schema version of Docker Compose, and the library should act as low level utility to implement the docker stack deploy command. That's why you probably run into issues when trying to load non-trivial v2 Compose files and that also the reason why the repo contains the -v3 suffix.

To answer your question where the lib should make sense: it is a pure JVM library without dependencies to a lokal docker binary and it won't hinder you from loading docker-compose.yml files. It should always work as replacement for a docker-stack.yml (compose v3) loader, and it could successfully load docker-compose.yml files, but some compose v2 specific attributes aren't considered for deserialisation. I guess making it compatible with the v2 compose format won't be too hard, but that's not my focus and I personally don't have enough time to maintain both variants. I'm open for contributions or other help, though! :-)

gesellix commented 7 years ago

Which use cases/commands would you like to implement in pure Java code?

daniellavoie commented 7 years ago

Hi gesellix, nice work ! If I understood well, docker-cloud stak.yaml files are the same than v3 compose ?

gesellix commented 7 years ago

@daniellavoie No, that's yet another format for Docker Cloud and the naming doesn't even help very much. To clarify:

There's Docker Compose (focused on a single machine)
There's Docker Swarm (focused on a cluster of machines)
There's Docker Cloud (a management platform for your cluster. Supports both Standard mode (pure containers) as well as Swarm mode)
There's a Docker Compose .yml file format in several versions (1.x, 2.x, 3.x), with more or less subtle differences. It is recommended to use the recent v3 file format, but maybe you still need v2 for some properties being removed in v3.
Compose format 3.x is designed to work with Docker Swarm. docker stack deploy can use those .yml files -> https://docs.docker.com/compose/compose-file/compose-versioning/
Docker Cloud also knows a concept named "Stack", but that's a different one as docker stack .... That's why the stackfiles for Docker Cloud use a different format. -> https://docs.docker.com/docker-cloud/apps/stack-yaml-reference/

To complete the confusion: you can enable Swarm mode in Docker Cloud and use Docker Stack to deploy a Compose v3 based stack.yml ;-)

Does that help?

daniellavoie commented 7 years ago

@gesellix It sure does :) Thanks for the complete picture

docker-client / docker-compose-v3

Lack of documentation #2