@@ -58,44 +58,80 @@ parseResponse (Right response) =
5858 Right r ->
5959 return $ Right r
6060
61+-- | Gets the version of the docker engine remote API.
6162getDockerVersion :: forall m. Monad m => DockerT m (Either DockerError DockerVersion)
6263getDockerVersion = requestHelper GET VersionEndpoint >>= parseResponse
6364
65+-- | Lists all running docker containers. Pass in defaultListOpts {all
66+-- = True} to get a list of stopped containers as well.
6467listContainers :: forall m. Monad m => ListOpts -> DockerT m (Either DockerError [Container])
6568listContainers opts = requestHelper GET (ListContainersEndpoint opts) >>= parseResponse
6669
70+-- | Lists all docker images.
6771listImages :: forall m. Monad m => ListOpts -> DockerT m (Either DockerError [Image])
6872listImages opts = requestHelper GET (ListImagesEndpoint opts) >>= parseResponse
6973
74+-- | Creates a docker container but does *not* start it. See
75+-- "CreateOpts" for a list of options and you can use "defaultCreateOpts"
76+-- for some sane defaults.
7077createContainer :: forall m. Monad m => CreateOpts -> DockerT m (Either DockerError ContainerID)
7178createContainer opts = requestHelper POST (CreateContainerEndpoint opts) >>= parseResponse
7279
73−-- TODO: Is this the correct return type? XXX
74−-- convert status code to unit or error
80+-- | Start a container from a given "ContainerID" that we get from
81+-- "createContainer". See "StartOpts" for a list of configuration options
82+-- for starting a container. Use "defaultStartOpts" for sane defaults.
7583startContainer :: forall m. Monad m => StartOpts -> ContainerID -> DockerT m (Either DockerError ())
7684startContainer sopts cid = requestUnit POST $ StartContainerEndpoint sopts cid
7785
86+-- | Attempts to stop a container with the given "ContainerID" gracefully
87+-- (SIGTERM).
88+-- The docker daemon will wait for the given "Tiemout" and then send
89+-- a SIGKILL killing the container.
7890stopContainer :: forall m. Monad m => Timeout -> ContainerID -> DockerT m (Either DockerError ())
7991stopContainer t cid = requestUnit POST $ StopContainerEndpoint t cid
8092
93+-- | Sends a "Signal" to the container with the given "ContainerID". Same
94+-- as "stopContainer" but you choose the signal directly.
8195killContainer :: forall m. Monad m => Signal -> ContainerID -> DockerT m (Either DockerError ())
8296killContainer s cid = requestUnit POST $ KillContainerEndpoint s cid
8397
98+-- | Restarts a container with the given "ContainerID".
8499restartContainer :: forall m. Monad m => Timeout -> ContainerID -> DockerT m (Either DockerError ())
85100restartContainer t cid = requestUnit POST $ RestartContainerEndpoint t cid
86101
102+-- | Pauses a container with the given "ContainerID"
87103pauseContainer :: forall m. Monad m => ContainerID -> DockerT m (Either DockerError ())
88104pauseContainer cid = requestUnit POST $ PauseContainerEndpoint cid
89105
106+-- | Unpauses a container with the given "ContainerID".
90107unpauseContainer :: forall m. Monad m => ContainerID -> DockerT m (Either DockerError ())
91108unpauseContainer cid = requestUnit GET $ UnpauseContainerEndpoint cid
92109
110+-- | Deletes a container with the given "ContainerID".
111+-- See "DeleteOpts" for options and use "defaultDeleteOpts" for sane
112+-- defaults.
93113deleteContainer :: forall m. Monad m => DeleteOpts -> ContainerID -> DockerT m (Either DockerError ())
94114deleteContainer dopts cid = requestUnit DELETE $ DeleteContainerEndpoint dopts cid
95115
116+-- | Gets "ContainerDetails" for a given "ContainerID".
96117inspectContainer :: forall m . Monad m => ContainerID -> DockerT m (Either DockerError ContainerDetails)
97118inspectContainer cid = requestHelper GET (InspectContainerEndpoint cid) >>= parseResponse
98119
120+-- | Get's container's logs for a given "ContainerID".
121+-- This will only work with the "JsonFile" "LogDriverType" as the other driver types disable
122+-- this endpoint and it will return a DockerError.
123+--
124+-- See "LogOpts" for options that you can pass and
125+-- "defaultLogOpts" for sane defaults.
126+--
127+-- __NOTE__: Currently streaming logs is
128+-- not supported and this function will fetch the entire log that the
129+-- container produced in the json-file on disk. Depending on the logging
130+-- setup of the process in your container this can be a significant amount
131+-- which might block your application...so use with caution.
132+--
133+-- The recommended method is to use one of the other "LogDriverType"'s available (like
134+-- syslog) for creating your containers.
99135getContainerLogs :: forall m. Monad m => LogOpts -> ContainerID -> DockerT m (Either DockerError BSL.ByteString)
100136getContainerLogs logopts cid = fmap responseBody <$> requestHelper GET (ContainerLogsEndpoint logopts False cid)
101137