Skip to content
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

Closed
mauricioklein opened this issue Jul 10, 2015 · 10 comments
Closed

Lack of documentation #17

mauricioklein opened this issue Jul 10, 2015 · 10 comments

Comments

@mauricioklein
Copy link

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

@gesellix
Copy link
Owner

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
Copy link
Author

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
Copy link
Owner

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

@mauricioklein
Copy link
Author

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
Copy link
Owner

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
Copy link
Owner

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
Copy link
Owner

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

@mauricioklein
Copy link
Author

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/

@ghost
Copy link

ghost commented Apr 6, 2016

@mauricioklein Any word on those docs?

@gesellix
Copy link
Owner

gesellix commented Apr 6, 2016

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

@mauricioklein mauricioklein closed this as not planned Won't fix, can't repro, duplicate, stale Oct 12, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants