• Stars
    star
    452
  • Rank 94,320 (Top 2 %)
  • Language
    Go
  • License
    MIT License
  • Created over 8 years ago
  • Updated 10 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tools for browsing and manipulating docker registries.

Build Status

What is it?

Docker-ls is a set of CLI tools for browsing and manipulating docker registries. In particular, docker-ls can handle authentication and display the sha256 content digests associated with tags.

What registries are supported

Only V2 registries are supported. Both HTTP Basic auth and Docker style token authentication are supported for authentication.

Installation

Six ways there are to attain enlightenment.

Precompiled binaries

Just download precompiled binaries for your platform from GitHub.

MacOS / Homebrew

You can install docker-ls directly from Homebrew:

brew install docker-ls

Gentoo / portage

emerge docker-ls

NixOS

nix-env -iA nixos.docker-ls

Arch Linux

Package in the AUR available.

Docker

If you have Docker installed, you may want to try this option. Clone the repository and do:

docker build -t docker-ls .

Example of running container:

$ docker run -it docker-ls docker-ls tags library/consul
requesting list . done
repository: library/consul
tags:
- latest
- v0.6.4

Or create aliases:

$ alias docker-ls='docker run -it docker-ls docker-ls'
$ alias docker-rm='docker run -it docker-ls docker-rm'

So you can do:

$ docker-ls tags library/consul
requesting list . done
repository: library/consul
tags:
- latest
- v0.6.4

and:

$ docker-rm | head -n 3
usage: docker-rm [options] <repository:reference>

Delete a tag in a given repository.

Go get

Provided that you sport an installation of golang, the latest version from master can be installed via

go get -d github.com/mayflower/docker-ls/cli/...
go generate github.com/mayflower/docker-ls/lib/...
go install github.com/mayflower/docker-ls/cli/...

Isn't a simple go get github.com/mayflower/docker-ls/cli/... sufficient, you ask? Indeed it is, but including the generate step detailed above will encode verbose version information in the binaries.

Usage

Docker-ls contains two CLI tools: docker-ls and docker-rm .

docker-ls

docker-ls is a browser for docker registries. Output is either encoded as YAML or as JSON.

Several subcommands are available

  • docker-ls repositories Obtains a list of repositories on the server. This is not supported by the official docker hub.
  • docker-ls tags Lists all tags in a a particular repository.
  • docker-ls tag Inspect a particular tag. This command displays a condensed version of the corresponding manifest by default, but the --raw-manifest option can be used to dump the full manifest. The --parse-history option can be used to display the JSON-encoded history within the manifest.

Authentication and credentials

docker-ls supports the following authentication methods:

  • "Classic" docker registry token authentication. This is the default if credentials are supplied on the command line. If credentials are taken from a previous docker login, this is the default unless the credentials contains an identity token.
  • OAuth2 authentication. This is used if the credentials are taken from a previous docker login and contain an identity token.
  • Basic auth. This needs to be requested explicitly on the CLI.

Credentials are automatically taken from a previous docker login or specified on the command line. docker-ls implicitly uses the same credential store and helpers used by docker.

Logging into Amazon ECR requires Basic auth, the same goes for Google GCR.

Important command line flags

This list is not exhaustive; please consult the command line (-h) help for all options.

  • --registry <url> (-r) Connect to the registry at <url>. The URL must include the protocol (http / https). By default, docker-ls targets the official docker hub.

  • --user <user> (-u) Username for authentication.

  • --password <password> (-p) Password for authentication.

  • --user-agent <agent string> Use a custom user agent.

  • --interactive-password(-i) Read the password from an interactive prompt.

  • --level <depth> (-l) The repositories and tags subcommands support this option for recursive output. Depths 0 (default) and 1 are supported. Please note recursion means more API requests and may be slow.

  • --json (-j) Switch output format from YAML to JSON.

  • --template (-t) Use a named golang template from the configuration for output (see below)

  • --template-source Use the specified template for output (see below)

  • --basic-auth Use HTTP basic auth for authentication (instead of token authentication).

  • --allow-insecure Do not validate SSL certificates (useful for registries secured with a self-signed certificate).

  • --manifest-version Request either manifest version V2.1 (--manifest-version 1 or manifest version V2.2 (--manifest-version 2, default) from the registry. Please note that deleting manifests from registry version >= 2.3 will work only with content digests from a V2.2 manifest.

  • --debug Enable debug output.

    WARNING: This is exactly what the name suggests: debugging output. It contains raw data structures, may include your credentials in verbatim and may or may not help you. Use with care.

Examples

List all repositories in a custom registry:

docker-ls repositories --registry https://my.registry.org --user hanni --password hanni123

List all repositories in a custom registry, including their tags:

docker-ls repositories --registry https://my.registry.org --user hanni --password hanni123 --level 1

List all tags in stuff/busybox using HTTP basic auth

docker-ls tags --registry https://my.registry.org --user hanni --password hanni123 --basic-auth stuff/busybox

Inspect tag stuff/busybox:latest, no authentication, JSON output.

docker-ls tag --registry https://my.registry.org --json stuff/busybox:latest

Inspect tag stuff/busybox:latest, no authentication, dump the raw manifest with parsed history as JSON.

docker-ls tag --registry https://my.registry.org --json --raw-manifest --parse-history stuff/busybox:latest

Notes considering the offical registry

If no registry is specified, docker-ls will target the official registry server at https://index.docker.io. Please note that:

  • The official registry does not support repository listing via docker-ls repositories
  • Official repositories must be prefixed with library/, e.g. docker-ls tags library/debian

docker-rm

docker-rm can delete particular tags. Example:

docker-rm --registry https://my.registry.org --user someuser --password somepass busybox:sha256:51fef[...]

(the digest has been truncated for brevity). Please consult the command line help for a full list of all arguments.

Some remarks:

  • The tag must be specified as a sha256 content digest.
  • While tags can be deleted, the current registry implementation will (to the best of my knowledge) not free the space associated with any resulting unused layers
  • Deleting stuff is currently disabled by default in the official registry and needs to be enabled explicitly β€” check out this issue for details.
  • Content digests obtained with --manifest-version 1 will not work with registry version >= 2.3.
  • BE CAREFUL! The API does not implement undelete :)

Using a proxy

docker-ls supports HTTP / HTTPS proxies configured via the corresponding canonical environment variables. Check out the corresponding documentation for details.

Configuration via config files and environment variables

All options that can be specified via CLI flags can be read from a config file or from an environment variables. The priority is CLI flag > environment variable > config file.

Config files

By default, both tools try to read ~/.docker-ls.[yaml|json|toml|...] (please check the Viper documentation for a full list of the supported formats). The names of the keys in the file are the long names of the CLI flags. For example, the following YAML file would configure registry URL and username

registry: https://foo.bar.com
user: foo

Other config files can be specified via the --config option.

Template Output

Output of the various docker-ls subcommands can be further customized by using golang templates.

Predefined templates

Named templates can be configured in the templates section of the configuration file. When docker-ls is invoked, the -t parameter (see above) can be used to select a named template for formatting the output.

Example: The following YAML section defines a template that outputs the list of tags in a repository as a simple HTML document.

templates:
  taglist_html: |
    <head></head>
    <body>
        <h1>Tags for repository {{ html .Repository }}</h1>
        <ul>
            {{- range .Tags }}
            <li>{{ html . }}</li>
            {{- end }}
        </ul>
    </body>

It can be invoked by running i.e.

docker-ls tags -t taglist_html /library/debian

Inline templates

Simple templates can also be passed directly on the command line using the --template-source parameter:

docker-ls tag --template-source '{{ .TagName }}: {{ .Digest }}'  /library/debian:wheezy

Template variables

Inside templates, all fields of the corresponding JSON / YAML output can be accessed in pipeline expressions. The first letter of all field names is capitalized, with the exception of manifests that are directly returned from the registry by using docker-ls tag --raw-manifest: for those, the JSON / YAML field names are unchanged.

Environment variables

In addition to config files and CLI flags, environment variables can be used to specify options globally. The name is determined by taking the long CLI name, uppercasing replacing hyphens "-" with underscores "_" and prefixing the result with "DOCKER_LS_". For example, the following would enable interactive password prompts for all consecutive invocations:

export DOCKER_LS_INTERACTIVE_PASSWORD=1

Shell autocompletion

Both docker-ls and docker-rm support shell autocompletion for subcommands and options. To enable this, source the output of docker-ls autocomplete bash|zsh and docker-rm autocomplete bash|zsh in the running shell. In case of bash, this can be achieved with

$ source <(docker-ls autocomplete bash)

License

Docker-ls is distributed under the terms of the MIT license.

More Repositories

1

PHProjekt

The official PHProjekt 6 repository.
JavaScript
100
star
2

PayForMe

iOS client for Cospend on Nextcloud
HTML
67
star
3

wasted

Web Application STack for Extreme Development
Puppet
42
star
4

nixexprs

Public, Opinionated Mayflower NixOS Modules/Packages and other Expressions
Nix
38
star
5

gigger

Javascript Realtime Reporting Engine
JavaScript
32
star
6

go-repro

Request rewriting reverse proxy.
Go
28
star
7

libholiday

Holiday Calculation Library for PHP
PHP
26
star
8

cloudbot

A simple langchain demo containing an agent to help you with everything kubernetes and aws.
Python
23
star
9

nixborg

Tests your pull requests using Hydra
Python
20
star
10

Bytekit

Bytekit is a PHP extension that provides a userspace representation of the opcodes generated by the Zend engine compiler built into PHP.
C
20
star
11

cushymoco

a shop-agnostic native mobile app framework for e-commerce shops like OXID, Magento and Shopware
PHP
18
star
12

mo4-coding-standard

MO4 Coding Standard Rules for Codesniffer based on Symfony Coding Standards.
PHP
18
star
13

langchain_agents

Sourcecode fΓΌr den Workshop Autonome Agenten mit Langchain
Jupyter Notebook
16
star
14

slack_my_documents

Einfacher Slackbot zur Dokumentenrecherche auf Deutsch.
Python
15
star
15

postgraphile-audit-plugin

This plugin adds functionality to access pgMemento's audit data on an entity level from a postgraphile graphql api.
TypeScript
11
star
16

goldenbook

example project to showcase NixOS tests
Nix
9
star
17

argocd-nix-flakes-plugin

ArgoCD Plugin running Nix flakes apps
Jsonnet
8
star
18

hydra-jobs

Our jobs for the hydra CI
Nix
8
star
19

ExtJsPackages

ExtJS Packages by Mayflower
JavaScript
8
star
20

oxid-bepado

Connect an OXID eShop with the Bepado network.
PHP
7
star
21

cordova-android-movetasktoback

Export Activity::MoveTaskToBack in cordova. Allows to return to the previous activity programatically.
JavaScript
7
star
22

oTTo

Open Time Table organizer
Vue
7
star
23

demockrazy

A simple token based voting system
Python
7
star
24

geordi

Geordi (La Forge) is a small GitHub webhook receiver written in python publishing Puppet modules to the Forge
Python
6
star
25

pumuckl

Puppet Module Version Checker
Python
5
star
26

rusted

Tracks configuration changes of network devices in git. It's a RANCID^WOxidized replacement?
Rust
5
star
27

opsdroid-atlassian

Opsdroid plugin for atlassian webhooks
Python
5
star
28

PHP_CachegrindParser

A parser for cachegrind files, generating an xml format for CI usage and graphviz .dot files
PHP
5
star
29

puppet-hhvm

Installs and configures Facebook's HHVM with puppet
Puppet
4
star
30

sf2hackday

Symfony2 Hackday
JavaScript
4
star
31

agcod-java-client

Unofficial AGCOD (Amazon Gift Card On Demand) Client for Java
Java
4
star
32

sqlite-reverse-string

SQLite extension for reversing strings.
C
4
star
33

errbot-alerrtmanagerr

Get alerts from Prometheus Alertmanager via webhooks
Python
4
star
34

capnproto-typescript-k8s

kubernetes capnproto nestjs
TypeScript
4
star
35

wueshop-ai-forms

Wuerzburg form checker agent
Python
4
star
36

webassembly

JavaScript
4
star
37

pwdog

a secure credential management software utilizing GnuPG for encryption and access control.
Python
3
star
38

puppet-highlight

Puppet Syntax Highlighting for PHPStorm
PHP
3
star
39

PhprojektRemoteApi

Remote HTTP API to PHProjekt
PHP
3
star
40

phprojekt.com

JavaScript
3
star
41

microk8s-addons

Custom MicroK8s addons we use.
Shell
3
star
42

jira-vote

Voting tool for JIRA 6.x
PHP
3
star
43

nixpkgs-stats

Statistics on NixOS/nixpkgs development aggregated with pandas
Jupyter Notebook
3
star
44

mayrogue

JavaScript
3
star
45

marley

a modern ini editor
JavaScript
2
star
46

TypeScriptPrimer

TypeScript
2
star
47

postgraphile-tag-json-tools

TypeScript
2
star
48

project44

Mayflower open Mayday repository
Python
2
star
49

langchain-book

2
star
50

cordova-android-scrollbar

A cordova plugin that brings back the vertical scrollbar on Android
HTML
2
star
51

coding-dojos

Coding Dojos
JavaScript
2
star
52

ShimSham

Mayday project for fast business development.
JavaScript
2
star
53

popular-radar

A MVP that compares two buzzwords using different APIs
PHP
2
star
54

hkpeter

HKP Keyserver
PHP
2
star
55

rust-puppetfile

Small Puppetfile Parser
Rust
1
star
56

postgraphile-example

1
star
57

ShopwareAttributeRestApi

Shopware plugin that exposes free text fields (attributes) via REST API
PHP
1
star
58

tpp

Team Project Planner
PHP
1
star
59

mocoapp-client

Our fast and correct RUST library for the MOCO REST api
Rust
1
star
60

localbot

A local bot with smart agents, using a local GPU model.
Python
1
star
61

err-misc

Misc minimal errbot commands
Python
1
star
62

nestjs-mqtt-metrics-demo

NestJs app that collects mqtt data from a mqtt broker for instance mosquitto. The collected data will be emitted by prometheus app metrics endpoint.
TypeScript
1
star
63

timmy

Timetracking for Android
Java
1
star
64

puppet-magentoce

puppet module for Magento CE E-Commerce Shop Software
Puppet
1
star
65

baseboxes

sources for our vagrant baseboxes
Shell
1
star
66

nixos-intro-slides

HTML
1
star
67

telephone-game

TypeScript
1
star
68

err-rasa

Python
1
star
69

react-workshop

Nix
1
star
70

JID

XMPP identifiers (JID) for JavaScript
JavaScript
1
star