Docker Client

This is a low-level Docker Client written in Swift. It very closely follows the Docker API.

It fully uses the Swift concurrency features introduced with Swift 5.5 (async/await).

Docker API version support

This client library aims at implementing the Docker API version 1.41 (https://docs.docker.com/engine/api/v1.41). This means that it will work with Docker >= 20.10.

Current implementation status

Section	Operation	Support	Notes
Client connection	Local Unix socket	✅
	HTTP	✅
	HTTPS	✅

Docker daemon & System info	Ping	✅
	Info	✅
	Version	✅
	Events	✅
	Get data usage info	✅

Containers	List	✅
	Inspect	✅
	Create	✅
	Update	✅
	Rename	✅
	Start/Stop/Kill	✅
	Pause/Unpause	✅
	Get logs	✅
	Get stats	✅
	Get processes (top)	✅
	Delete	✅
	Prune	✅
	Wait	✅
	Filesystem changes	✅	untested
	Attach	✅	basic support ¹
	Exec	❌	unlikely ²
	Resize TTY	❌

Images	List	✅
	Inspect	✅
	History	✅
	Pull	✅	basic support
	Build	✅	basic support
	Tag	✅
	Push	✅
	Create (container commit)	✅
	Delete	✅
	Prune	✅

Swarm	Init	✅
	Join	✅
	Inspect	✅
	Leave	✅
	Update	✅

Nodes	List	✅
	Inspect	✅
	Update	✅
	Delete	✅

Services	List	✅
	Inspect	✅
	Create	✅
	Get logs	✅
	Update	✅
	Rollback	✅
	Delete	✅

Networks	List	✅
	Inspect	✅
	Create	✅
	Delete	✅
	Prune	✅
	(Dis)connect container	✅

Volumes	List	✅
	Inspect	✅
	Create	✅
	Delete	✅
	Prune	✅

Secrets	List	✅
	Inspect	✅
	Create	✅
	Update	✅
	Delete	✅

Configs	List	✅
	Inspect	✅
	Create	✅
	Update	✅
	Delete	✅

Tasks	List	✅
	Inspect	✅
	Get logs	✅

Plugins	List	✅
	Inspect	✅
	Get Privileges	✅
	Install	✅
	Remove	✅
	Enable/disable	✅
	Upgrade	✅	untested
	Configure	✅	untested
	Create	❌	TBD
	Push	❌	TBD

Registries	Login	✅	basic support

Docker error responses mgmt		🚧

✅ : done or mostly done

🚧 : work in progress, partially implemented, might not work

❌ : not implemented/supported at the moment.

Note: various Docker endpoints such as list or prune support filters. These are currently not implemented.

¹ Attach is currently not supported when connecting to Docker via local Unix socket, or when using a proxy. It uses the Websocket protocol.

² Docker exec is using an unconventional protocol that requires raw access to the TCP socket. Significant work needed in order to support it (swift-server/async-http-client#353).

Installation

Package.swift

import PackageDescription

let package = Package(
    dependencies: [
        .package(url: "https://github.com/m-barthelemy/DockerSwift.git", .branch("main")),
    ],
    targets: [
        .target(name: "App", dependencies: [
            ...
            .product(name: "DockerSwift", package: "DockerSwift")
        ]),
    ...
    ]
)

Xcode Project

To add DockerClientSwift to your existing Xcode project, select File -> Swift Packages -> Add Package Dependancy. Enter https://github.com/m-barthelemy/DockerSwift.git for the URL.

Usage Examples

Connect to a Docker daemon

Local socket (defaults to /var/run/docker.sock):

import DockerSwift

let docker = DockerClient()
defer {try! docker.syncShutdown()}

Remote daemon over HTTP:

import DockerSwift

let docker = DockerClient(daemonURL: URL(string: "http://127.0.0.1:2375")!)
defer {try! docker.syncShutdown()}

Remote daemon over HTTPS, using a client certificate for authentication:

import DockerSwift

var tlsConfig = TLSConfiguration.makeClientConfiguration()
tlsConfig.privateKey = NIOSSLPrivateKeySource.file("client-key.pem")
tlsConfig.certificateChain.append(NIOSSLCertificateSource.file("client-certificate.pem"))
tlsConfig.additionalTrustRoots.append(.file("docker-daemon-ca.pem"))
tlsConfig.certificateVerification = .noHostnameVerification

let docker = DockerClient(
    daemonURL: .init(string: "https://your.docker.daemon:2376")!,
    tlsConfig: tlsConfig
)
defer {try! docker.syncShutdown()}

Docker system info

Get detailed information about the Docker daemon

let info = try await docker.info()
print("• Docker daemon info: \(info)")

Get versions information about the Docker daemon

let version = try await docker.version()
print("• Docker API version: \(version.apiVersion)")

Listen for Docker daemon events

We start by listening for docker events, then we create a container:

async let events = try await docker.events()

let container = try await docker.containers.create(
    name: "hello",
    spec: .init(
        config: .init(image: "hello-world:latest"),
        hostConfig: .init()
    )
)

Now, we should get an event whose action is "create" and whose type is "container".

for try await event in try await events {
    print("\n••• event: \(event)")
}

Containers

List containers

Add all: true to also return stopped containers.

let containers = try await docker.containers.list()

Get a container details

let container = try await docker.containers.get("nameOrId")

Create a container

Note: you will also need to start it for the container to actually run.

The simplest way of creating a new container is to only specify the image to run:

let spec = ContainerSpec(
    config: .init(image: "hello-world:latest")
)
let container = try await docker.containers.create(name: "test", spec: spec)

Docker allows customizing many parameters:

let spec = ContainerSpec(
    config: .init(
        // Override the default command of the Image
        command: ["/custom/command", "--option"],
        // Add new environment variables
        environmentVars: ["HELLO=hi"],
        // Expose port 80
        exposedPorts: [.tcp(80)],
        image: "nginx:latest",
        // Set custom container labels
        labels: ["label1": "value1", "label2": "value2"]
    ),
    hostConfig: .init(
        // Memory the container is allocated when starting
        memoryReservation: .mb(64),
        // Maximum memory the container can use
        memoryLimit: .mb(128),
        // Needs to be either disabled (-1) or be equal to, or greater than, `memoryLimit`
        memorySwap: .mb(128),
        // Let's publish the port we exposed in `config`
        portBindings: [.tcp(80): [.publishTo(hostIp: "0.0.0.0", hostPort: 8000)]]
    )
)
let container = try await docker.containers.create(name: "nginx-test", spec: spec)

Update a container

Let's update the memory limits for an existing container:

let newConfig = ContainerUpdate(memoryLimit: .mb(64), memorySwap: .mb(64))
try await docker.containers.update("nameOrId", spec: newConfig)

Start a container

try await docker.containers.start("nameOrId")

Stop a container

try await docker.containers.stop("nameOrId")

Rename a container

try await docker.containers.rename("nameOrId", to: "hahi")

Delete a container

If the container is running, deletion can be forced by passing force: true

try await docker.containers.remove("nameOrId")

Get container logs

Logs are streamed progressively in an asynchronous way.

Get all logs:

let container = try await docker.containers.get("nameOrId")
      
for try await line in try await docker.containers.logs(container: container, timestamps: true) {
    print(line.message + "\n")
}

Wait for future log messages:

let container = try await docker.containers.get("nameOrId")
      
for try await line in try await docker.containers.logs(container: container, follow: true) {
    print(line.message + "\n")
}

Only the last 100 messages:

let container = try await docker.containers.get("nameOrId")
      
for try await line in try await docker.containers.logs(container: container, tail: 100) {
    print(line.message + "\n")
}

Attach to a container

Let's create a container that defaults to running a shell, and attach to it:

let _ = try await docker.images.pull(byIdentifier: "alpine:latest")
let spec = ContainerSpec(
    config: .init(
        attachStdin: true,
        attachStdout: true,
        attachStderr: true,
        image: "alpine:latest",
        openStdin: true
    )
)
let container = try await docker.containers.create(spec: spec)
let attach = try await docker.containers.attach(container: container, stream: true, logs: true)

// Let's display any output from the container
Task {
    for try await output in attach.output {
        print("• \(output)")
    }
}

// We need to be sure that the container is really running before being able to send commands to it.
try await docker.containers.start(container.id)
try await Task.sleep(for: .seconds(1))

// Now let's send the command; the response will be printed to the screen.
try await attach.send("uname")

Images

List the Docker images

let images = try await docker.images.list()

Get an image details

let image = try await docker.images.get("nameOrId")

Pull an image

Pull an image from a public repository:

let image = try await docker.images.pull(byIdentifier: "hello-world:latest")

Pull an image from a registry that requires authentication:

var credentials = RegistryAuth(username: "myUsername", password: "....")
try await docker.registries.login(credentials: &credentials)
let image = try await docker.images.pull(byIdentifier: "my-private-image:latest", credentials: credentials)

NOTE: RegistryAuth also accepts a serverAddress parameter in order to use a custom registry.

Creating images from a remote URL or from the standard input is currently not supported.

Push an image

Supposing that the Docker daemon has an image named "my-private-image:latest":

var credentials = RegistryAuth(username: "myUsername", password: "....")
try await docker.registries.login(credentials: &credentials)
try await docker.images.push("my-private-image:latest", credentials: credentials)

NOTE: RegistryAuth also accepts a serverAddress parameter in order to use a custom registry.

Build an image

The current implementation of this library is very bare-bones. The Docker build context, containing the Dockerfile and any other resources required during the build, must be passed as a TAR archive.

Supposing we already have a TAR archive of the build context:

let tar = FileManager.default.contents(atPath: "/tmp/docker-build.tar")
let buffer = ByteBuffer.init(data: tar)
let buildOutput = try await docker.images.build(
    config: .init(dockerfile: "./Dockerfile", repoTags: ["build:test"]),
    context: buffer
)
// The built Image ID is returned towards the end of the build output
var imageId: String!
for try await item in buildOutput {
    if item.aux != nil {
        imageId = item.aux!.id
    }
    else {
      print("\n• Build output: \(item.stream)")
    }
}
print("\n• Image ID: \(imageId)")

You can use external libraries to create TAR archives of your build context. Example with Tarscape (only available on macOS):

import Tarscape

let tarContextPath = "/tmp/docker-build.tar"
try FileManager.default.createTar(
    at: URL(fileURLWithPath: tarContextPath),
    from: URL(string: "file:///path/to/your/context/folder")!
)

Networks

List networks

let networks = try await docker.networks.list()

Get a network details

let network = try await docker.networks.get("nameOrId")

Create a network

Create a new network without any custom options:

let network = try await docker.networks.create(
  spec: .init(name: "my-network")
)

Create a new network with custom IPs range:

let network = try await docker.networks.create(
    spec: .init(
        name: "my-network",
        ipam: .init(
            config: [.init(subnet: "192.168.2.0/24", gateway: "192.168.2.1")]
        )
    )
)

Delete a network

try await docker.networks.remove("nameOrId")

Connect an existing Container to a Network

let network = try await docker.networks.create(spec: .init(name: "myNetwork"))
var container = try await docker.containers.create(
    name: "myContainer",
    spec: .init(config: .init(image: image.id))
)

try await docker.networks.connect(container: container.id, to: network.id)

Volumes

List volumes

let volumes = try await docker.volumes.list()

Get a volume details

let volume = try await docker.volumes.get("nameOrId")

Create a volume

let volume = try await docker.volumes.create(
  spec: .init(name: "myVolume", labels: ["myLabel": "value"])
)

Delete a volume

try await docker.volumes.remove("nameOrId")

Swarm

Initialize Swarm mode

let swarmId = try await docker.swarm.initSwarm()

Get Swarm cluster details (inspect)

The client must be connected to a Swarm manager node.

let swarm = try await docker.swarm.get()

Make the Docker daemon to join an existing Swarm cluster

// This first client points to an existing Swarm cluster manager
let swarmClient = Dockerclient(...)
let swarm = try await swarmClient.swarm.get()

// This client is the docker daemon we want to add to the Swarm cluster
let client = Dockerclient(...)
try await client.swarm.join(
    config: .init(
        // To join the Swarm cluster as a Manager node
        joinToken: swarmClient.joinTokens.manager,
        // IP/Host of the existing Swarm managers
        remoteAddrs: ["10.0.0.1"]
    )
)

Remove the current Node from the Swarm

Note: force is needed if the node is a manager

try await docker.swarm.leave(force: true)

Nodes

This requires a Docker daemon with Swarm mode enabled. Additionally, the client must be connected to a manager node.

List the Swarm nodes

let nodes = try await docker.nodes.list()

Remove a Node from a Swarm

Note: force is needed if the node is a manager

try await docker.nodes.delete(id: "xxxxxx", force: true)

Services

This requires a Docker daemon with Swarm mode enabled. Additionally, the client must be connected to a manager node.

List services

let services = try await docker.services.list()

Get a service details

let service = try await docker.services.get("nameOrId")

Create a service

Simplest possible example, we only specify the name of the service and the image to use:

let spec = ServiceSpec(
    name: "my-nginx",
    taskTemplate: .init(
        containerSpec: .init(image: "nginx:latest")
    )
)
let service = try await docker.services.create(spec: spec)

Let's specify a number of replicas, a published port and a memory limit of 64MB for our service:

let spec = ServiceSpec(
    name: "my-nginx",
    taskTemplate: .init(
        containerSpec: .init(image: "nginx:latest"),
        resources: .init(
            limits: .init(memoryBytes: .mb(64))
        ),
        // Uses default Docker routing mesh mode
        endpointSpec: .init(ports: [.init(name: "HTTP", targetPort: 80, publishedPort: 8000)])
    ),
    mode: .replicated(2)
)
let service = try await docker.services.create(spec: spec)

What if we then want to know when our service is fully running?

var index = 0 // Keep track of how long we've been waiting
repeat {
    try await Task.sleep(for: .seconds(1))
    print("\n Service still not fully running!")
    index += 1
} while try await docker.tasks.list()
      .filter({$0.serviceId == service.id && $0.status.state == .running})
      .count < 1 /* number of replicas */ && index < 15
print("\n Service is fully running!")

What if we want to create a one-off job instead of a service?

let spec = ServiceSpec(
    name: "hello-world-job",
    taskTemplate: .init(
        containerSpec: .init(image: "hello-world:latest"),
        ...
    ),
    mode: .job(1)
)
let job = try await docker.services.create(spec: spec)

Something more advanced? Let's create a Service:

connected to a custom Network
storing data into a custom Volume, for each container
requiring a Secret
publishing the port 80 of the containers to the port 8000 of each Docker Swarm node
getting restarted automatically in case of failure

let network = try await docker.networks.create(spec: .init(name: "myNet", driver: "overlay"))
let secret = try await docker.secrets.create(spec: .init(name: "myPassword", value: "blublublu"))
let spec = ServiceSpec(
    name: "my-nginx",
    taskTemplate: .init(
        containerSpec: .init(
            image: "nginx:latest",
            // Create and mount a dedicated Volume named "myStorage" on each running container. 
            mounts: [.volume(name: "myVolume", to: "/mnt")],
            // Add our Secret. Will appear as `/run/secrets/myPassword` in the containers.
            secrets: [.init(secret)]
        ),
        resources: .init(
            limits: .init(memoryBytes: .mb(64))
        ),
        // If a container exits or crashes, replace it with a new one.
        restartPolicy: .init(condition: .any, delay: .seconds(2), maxAttempts: 2)
    ),
    mode: .replicated(1),
    // Add our custom Network
    networks: [.init(target: network.id)],
    // Publish our Nginx image port 80 to 8000 on the Docker Swarm nodes
    endpointSpec: .init(ports: [.init(name: "HTTP", targetPort: 80, publishedPort: 8000)])
)
  
let service = try await docker.services.create(spec: spec)

Update a service

Let's scale an existing service up to 3 replicas:

let service = try await docker.services.get("nameOrId")
var updatedSpec = service.spec
updatedSpec.mode = .replicated(3)
try await docker.services.update("nameOrId", spec: updatedSpec)

Get service logs

Logs are streamed progressively in an asynchronous way.

Get all logs:

let service = try await docker.services.get("nameOrId")
      
for try await line in try await docker.services.logs(service: service) {
    print(line.message + "\n")
}

Wait for future log messages:

let service = try await docker.services.get("nameOrId")
      
for try await line in try await docker.services.logs(service: service, follow: true) {
    print(line.message + "\n")
}

Only the last 100 messages:

let service = try await docker.services.get("nameOrId")
      
for try await line in try await docker.services.logs(service: service, tail: 100) {
    print(line.message + "\n")
}

Rollback a service

Suppose that we updated our existing service configuration, and something is not working properly. We want to revert back to the previous, working version.

try await docker.services.rollback("nameOrId")

Delete a service

try await docker.services.remove("nameOrId")

Secrets

This requires a Docker daemon with Swarm mode enabled.

Note: The API for managing Docker Configs is very similar to the Secrets API and the below examples also apply to them.

List secrets

let secrets = try await docker.secrets.list()

Get a secret details

Note: The Docker API doesn't return secret data/values.

let secret = try await docker.secrets.get("nameOrId")

Create a secret

Create a Secret containing a String value:

let secret = try await docker.secrets.create(
  spec: .init(name: "mySecret", value: "test secret value 💥")
)

You can also pass a Data value to be stored as a Secret:

let data: Data = ...
let secret = try await docker.secrets.create(
  spec: .init(name: "mySecret", data: data)
)

Update a secret

Currently, only the labels field can be updated (Docker limitation).

try await docker.secrets.update("nameOrId", labels: ["myKey": "myValue"])

Delete a secret

try await docker.secrets.remove("nameOrId")

Plugins

List installed plugins

let plugins = try await docker.plugins.list()

Install a plugin

Note: the install() method can be passed a credentials parameter containing credentials for a private registry. See "Pull an image" for more information.

// First, we fetch the privileges required by the plugin:
let privileges = try await docker.plugins.getPrivileges("vieux/sshfs:latest")

// Now, we can install it
try await docker.plugins.install(remote: "vieux/sshfs:latest", privileges: privileges)

// finally, we need to enable it before using it
try await docker.plugins.enable("vieux/sshfs:latest")

Credits

This is a fork of the great work at https://github.com/alexsteinerde/docker-client-swift

License

This project is released under the MIT license. See LICENSE for details.

Contribute

You can contribute to this project by submitting a detailed issue or by forking this project and sending a pull request. Contributions of any kind are very welcome :)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Docker Client

Docker API version support

Current implementation status

Installation

Package.swift

Xcode Project

Usage Examples

Connect to a Docker daemon

Docker system info

Containers

Images

Networks

Volumes

Swarm

Nodes

Services

Secrets

Plugins

Credits

License

Contribute

Files

README.md

Latest commit

History

README.md

File metadata and controls

Docker Client

Docker API version support

Current implementation status

Installation

Package.swift

Xcode Project

Usage Examples

Connect to a Docker daemon

Docker system info

Containers

Images

Networks

Volumes

Swarm

Nodes

Services

Secrets

Plugins

Credits

License

Contribute