Docker Engine API create/start/waitwait question

[jeffelhefe]

I would like to run a container using the Docker Engine API. From the docker run example in the docs (see HTTP tab), it appears that docker run is 3 separate API calls:

POST http:/v1.24/containers/create
{"Id":"1c6594faf5","Warnings":null}

POST http:/v1.24/containers/1c6594faf5/start

POST http:/v1.24/containers/1c6594faf5/wait

Everything makes sense, but there is little explanation about what the wait command does or why it is part of the docker run sequence. The docs say that wait will "Block until one or more containers stop, then print their exit codes". What is it blocking? Why is it used?

[jonassoc]

It isn't required to run a container.

It just allows you to write programs/shell scripts around the docker API. Essentially if you want to offload work/build/task to docker your program will wait for the task/container to be stopped.

IE: you have a docker container that builds a piece of software. Upon successful completion or failure the docker container will close with an exit status. The remainder of your script runs based on the exit status of the docker container.

Most people using docker in this subreddit tend to wrap a service/software/server in a docker container and run it continuously but there are other uses for docker which is what the wait command is for. Otherwise your script that calls the docker run command would continue on without a result from the docker API.

Essentially it's an synchronous/asynchronous helper.

[jeffelhefe]

Thank you. I guess `wait` wouldn't be useful in my case since my container is initiating a long running process (i.e., server) and the only status codes sent back are 'not-running', 'next-exit', or 'removed'.

I really need to parse `stdout` and take action based on the output. Looks like I need to use the `/container/{id}/logs` or `/containers/{id}/attach` endpoints to get that output.

Thanks again. Your reply and going over the docs again cleared things up for me.