New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Lack of documentation #17

Open
mauricioklein opened this Issue Jul 10, 2015 · 10 comments

Comments

Projects
None yet
3 participants
@mauricioklein

mauricioklein commented Jul 10, 2015

Great lib, but the lack of documentation difficult the usage and even the evolution by community.

@gesellix

This comment has been minimized.

Owner

gesellix commented Jul 10, 2015

Hey, thanks!

Due to many other things to do, I have to admit that the documentation has less priority. Would you like to help? I would need to know where you've been stuck when trying to use this library. So, what would you miss beyond a basic introduction? I'm not sure if the complete api should be documented, because most of it should be conform to the official Docker remote api.

@mauricioklein

This comment has been minimized.

mauricioklein commented Jul 10, 2015

Hello!

Sure I can help.
I'm currently using it in a work project, so it's helping me to figure out what's the basic workflow.
Once I'm done here, I'll start evolving Read me. It's not a proper documentation, but I'ts a good start point for new users.

Cheers o/

@gesellix

This comment has been minimized.

Owner

gesellix commented Jul 10, 2015

sounds great 👍 - if you need any help or have questions (or even find bugs), just leave a note here!

@mauricioklein

This comment has been minimized.

mauricioklein commented Jul 10, 2015

Thanks!

I'm creating the client like this
DockerClientImpl dockerClient = new DockerClientImpl(host)
dockerClient.auth([path to auth file])

Is that correct? Am I missing something?!

Also, have you implemented any method to generate containerConfig, as provided by Spotify's API?

Thanks o/

@gesellix

This comment has been minimized.

Owner

gesellix commented Jul 11, 2015

For auth/login, the default ~/.dockercfg can be used like this:

def authConfig = dockerClient.readDefaultAuthConfig()
dockerClient.auth(authConfig)

So, the authConfig is a map with the properties like described in the official remote api docs.

Note: the auth is only used to verify your auth file. The dockerClient won't keep the credentials in memory, which is why you have to pass it for other calls like pull or push as base64 encoded String. You can find an example there: https://github.com/gesellix-docker/docker-client/blob/master/src/integrationTest/groovy/de/gesellix/docker/client/DockerClientImplIntegrationSpec.groovy#L173

@gesellix

This comment has been minimized.

Owner

gesellix commented Jul 11, 2015

On the other question for a more explicit api: The docker-client doesn't provide any types or interfaces for the containerConfig or other payload. So the best way is to understand the remote api and manually pass a map with your container config. An example can be found in the integration tests as well: https://github.com/gesellix-docker/docker-client/blob/master/src/integrationTest/groovy/de/gesellix/docker/client/DockerClientImplIntegrationSpec.groovy#L390

I don't prefer adding explicit interfaces to the docker-client because I'd like to stay compatible to old and even new api versions. In my experience the docker-client didn't have any issues with api changes and I would expect a user to understand which properties to use.

If you prefer some more explicit types or some kind of "help" via the docker client's api, I would suggest you to have a look at the docker-java library. It is well maintained and supports current api versions, but there are two main differences to my docker-client implementation:

  1. If you need a special property which isn't supported in its api, you would need to submit a pull request. That's ok, but you would have to wait for them to release the change (or rely on snapshots).
  2. They rely on JAX-RS/Apache Http Client which may be produce dependency or runtime issues in your environment. I started with an Apache Http Client, but dropped the dependency and re-implemented a minimal http client on top of the default Java SDK.
@gesellix

This comment has been minimized.

Owner

gesellix commented Jul 19, 2015

@mauricioklein hey, did you make any progress or do you have questions? I hope the docker-client isn't too much confusing ;-)

@mauricioklein

This comment has been minimized.

mauricioklein commented Jul 20, 2015

Hey man!
Don't worry, we're creating the necessary interfaces, based on your low level client.
Once our tests are done I'll improve your docs.

Thanks o/

@trishayy

This comment has been minimized.

trishayy commented Apr 6, 2016

@mauricioklein Any word on those docs?

@gesellix

This comment has been minimized.

Owner

gesellix commented Apr 6, 2016

@trishayy may I ask if you already tried to use the docker-client? Where did you miss documentation?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment