A tiny, easy-to-use Go SDK for controlling the Docker Engine. Start and stop containers, pull images with streamed progress, save and stream logs, inspect resource usage, and map ports — all in a small, readable Go package.
This README is intentionally simple and focused so you can get started quickly.
# run the example (talks to /var/run/docker.sock)
go run ./examples
# show running containers
docker ps
# stop / remove container when done
docker stop webapp
docker rm webappOpen the host URL printed by the example (e.g. http://localhost:37255) to view the running nginx page.
- Connects to Docker via UNIX socket (
/var/run/docker.sock). - Checks local Docker version vs latest GitHub release.
- Pulls images with streamed progress (prevents false 500 errors).
- Starts containers with optional host→container port mapping. If you pass an empty host port, the SDK picks a free host port automatically and binds it to the requested container port.
- Auto-cleans existing containers with the same name (stop + remove) before creating a new one.
- Stops and removes containers.
- Fetches resource usage (CPU% and memory in MB) via Docker
/stats?stream=false. - Saves container logs to
./logs/<name>_<timestamp>.logand supports streaming logs to stdout.
- Go 1.20+ installed.
- Docker Engine running locally, and your user must be able to access
/var/run/docker.sock(either run as a user in thedockergroup or usesudo).
- Clone or open the project directory:
cd ~/Desktop/dockergo- Run the example program:
go run ./examplesThe example will:
- Pull
nginx:latestif needed. - Start a container named
webapp. - Map a free host port → container port
80(unless you provide a specific host port). - Print resource usage and save logs to
./logs/.
- Find the mapped host port (the example prints it, or run):
docker ps
# or to get the host port directly
docker inspect --format='{{(index (index .NetworkSettings.Ports "80/tcp") 0).HostPort}}' webapp-
Open the page in your browser:
http://localhost:<host-port> -
Stop & remove when done:
docker stop webapp
docker rm webappCreate a client:
cli := dockergo.NewClient("") // empty = /var/run/docker.sockUseful functions:
cli.WaitForDocker(timeout time.Duration) error— wait until Docker daemon respondscli.CheckVersion() (*VersionInfo, error)— compare local vs latest Docker versioncli.StartContainer(image, name, hostPort, containerPort string) error— create and start a container; passhostPort==""to auto-assign a free host portcli.StopContainer(nameOrID string) error— stop containercli.RemoveContainer(nameOrID string) error— remove container (force)cli.GetResourceUsage(nameOrID string) (*ResourceUsage, error)— returns CPU% and memory in MBcli.SaveLogs(nameOrID string) (string, error)— save logs to./logs/<name>_<timestamp>.logcli.StreamLogs(nameOrID string, follow bool) error— stream logs to stdout
dockergo/
├── client.go # connects to Docker socket
├── containers.go # start/stop/create/remove, port mapping, stats
├── logs.go # save & stream logs
├── utils.go # helpers (http, version compare)
├── version.go # docker version + github check
├── types.go # shared structs
├── examples/
│ └── main.go # demo: start nginx, print stats, save logs
└── logs/ # generated logs by examples
- Permissions: your process must be able to access
/var/run/docker.sock(usedockergroup orsudo). - Port allocation: when the SDK auto-picks a host port there is a tiny race window between allocation and container creation; extremely rare but possible. If you need absolute guarantees, use explicit port numbers or let the SDK retry on conflict.
- GitHub rate limits:
CheckVersion()uses unauthenticated GitHub API calls and may be rate-limited. Consider adding token support for production. - Image caching: the SDK will re-pull images if you delete them; otherwise local cache is used.