Move .dockercfg to $XDG_CONFIG_HOME (a.k.a. ~/.config)

[yajo]

Right now Docker saves its configuration in $HOME/.dockercfg file by default. This pollutes the home dir and disables chances of version-controlling the config directory.

Please move config files to $XDG_CONFIG_HOME/docker/<whatever> to follow the Freedesktop guidelines.

[runcom]

Right now Docker saves its configuration in $HOME/.dockercfg file by default.

Docker it's now using ~/.docker/config.json I'm also gonna deprecate .dockercfg as per https://github.com/docker/docker/pull/20572#discussion_r53918494

Overall I think this makes sense btw, I'm willing to propose a PR to do this

ping @thaJeztah

[runcom]

ping @tianon @duglin also

[thaJeztah]

IIRC, there has been a discussion on that, but I don't remember why it wasn't done at the time

[tianon]

https://github.com/docker/docker/pull/3068#issuecomment-32469188 is the oldest reference I can find

[tianon]

Reading through that, I can honestly say that I've seen more CLI apps use ~/.config since participating in that thread; for example, my ~/.config now has syncthing and htop in it. :smile:

Do you think the migration would be manageable, @runcom?

Alex does make a good point there about actually following the spec (http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html), not just swapping our hard-coded ~/.docker out for ~/.config/docker. :smile: We also support DOCKER_CONFIG, so that'll play in before all the XDG stuff.

[vdemeester]

I would :heart: that too :stuck_out_tongue_closed_eyes:

[thaJeztah]

Thanks for searching @tianon; that was exactly the discussion I had in mind. I know at the time the discussion was about daemon config and client-config; do we still use ~/.docker for daemon options actually?

[runcom]

Do you think the migration would be manageable, @runcom?

I think it will, @vdemeester wanna take a look? :angel:

[vdemeester]

All right, #dibs on it :stuck_out_tongue_closed_eyes:

[thaJeztah]

Haha

[runcom]

do we still use ~/.docker for daemon options actually?

no we don't afaict

[tianon]

$ ls -l ~/.docker/
total 4
-rw------- 1 tianon tianon 766 Feb 17 19:47 config.json

No more key.json! :smile:

[thaJeztah]

thanks for checking @tianon

[LK4D4]

ping @thaJeztah @vdemeester for update

[vdemeester]

Assigning this to myself… had a little of work before 1.12. I should rebase and restart from there :angel:

[jcrben]

How do you see this playing out in terms of how files will be split into XDG_DATA_HOME, XDG_CACHE_HOME, and XDG_CONFIG_HOME?

For example, the machines folder that I have in my .docker is definitely data, although it might be nice to version control a small file or two reflecting the existence and configuration of those machines...

[yajo]

I'd consider config your tls certs, your config.json. Your machines would be data, the b2d iso too. Cache would be cache obviously.

You can always separately version-control both, or have an additional $DOCKER_DATA_HOME pointing to $XDG_DATA_HOME/docker/data if you need further customisation. But I think it is more common to version-control your whole XDG_CONFIG_HOME. No survey available obviously :laughing:.

[nirfse]

Is there any roadmap of this issue?

[iandstanley]

I'm guessing there's still no movement on this?

~/.docker is not the first choice to have this.

the correct approach should be ...

1. test for the XDG directories ... if found use them
2. fail back to ~/.docker

we shouldn't be spamming the users home directory when there's a perfectly good solution here

[remcohaszing]

Docker reads ~/$XDG_CONFIG_HOME/docker/config.json. However, some commands, subcommands from docker and third party, still create ~/.docker/config.json.

I have the following ~/.config/docker/config.json and authentication works based on these settings:

{
	"auths": {
		"https://index.docker.io/v1/": {},
		"registry.gitlab.com": {}
	},
	"HttpHeaders": {
		"User-Agent": "Docker-Client/19.03.3 (linux)"
	},
	"credsStore": "secretservice"
}

I do recall having to delete ~/.docker from time to time, although it doesn’t exist at the moment of writing this comment.

[thaJeztah]

Docker reads ~/$XDG_CONFIG_HOME/docker/config.json

I think it's currently only used when using rootless mode, in which case it was used to set DOCKER_CONFIG

[thaJeztah]

There was a pull request to implement this (https://github.com/moby/moby/pull/30025), but it needed more work and discussion https://github.com/moby/moby/pull/30025#issuecomment-293979818

We discussed it on the Maintainer session. We need to discuss more on the related issue (#20693), mainly about what to do when migrating, what to do if there is multiple configuration files (old path, new path) and if this should work only on linux, and/or only if XDG_CONFIG_DIR is set.

I'll close this for now. Let's continue discussing it on #20693.

While using XDG_CONFIG_DIR should not be too complicated for a fresh/new setup, we should take migration of existing installations into account. Also, there's many scripts, tools and CI configurations "in the wild" that currently rely on the hard-coded ~/.docker/ path to be used for the CLI configuration (this may include, e.g. docker-compose, and possibly docker cli plugins). Having those tools updated will take time, so we need to be sure there's a migration path (which could even involve having ~/.docker/ symlinked to the new location, or vice-versa.

So, thinks to discuss;

• How to migrate? Do we want to automatically migrate, or only check for the old path (~/.docker/), and fall back to XDG_CONFIG_DIR
• What to use if XDG_CONFIG_HOME is not set? The specification specifies; "If $XDG_CONFIG_HOME is either not set or empty, a default equal to $HOME/.config should be used". Perhaps that's ok if we continue to use ~/.docker/ as first location to check.
• What to use on macOS? macOS has a bit of a "split" personality.
  • Some users work from the command-line and try to (and expect) it to closely match Linux, in which case $XDG_CONFIG_HOME/docker or ~/.config/docker would be good choices
  • Some users expect it to follow the macOS conventions, which means that paths inside ~/Library/.... should be used.
    • note that Golang chose "macOS" native paths https://github.com/golang/go/commit/ebdc24c3d334132542daa7c57246389e0b259227, so uses ~/Library/Preferences/ as path. Golang also dictates that $HOME is set, which is not always the case, so can't be used by us.
• Should we discuss storing sensitive data separate? https://github.com/moby/moby/pull/30025#issuecomment-282271406

[ptman]

Note, that according to the specification, there's no $XDG_CONFIG_DIR, only $XDG_CONFIG_DIRS and $XDG_CONFIG_HOME.

[FCamborda]

The setup experience could be improved if Docker would support XDG. I think this could be a good priority flow: If DOCKER_CONFIG is set, simply use that. If XDG_CONFIG_HOME is set and nonempty, the user quite likely subscribes to the XDG convention and would expect the Docker config to be there. If XDG_CONFIG_HOME is not set, then I would in both cases print a warning

1. Check if $HOME/.docker/config.json exists and check if $HOME/.config/docker/config.json exist.
2. If both exist, you could have a deprecation period where $HOME/.docker/config.json is read, but warn that in the future in such cases, only $HOME/.config/docker/config.json will be the only one used. Not adhering to $HOME/.docker/config.json in the future means it's not really XDG compliant.
3. If only one of them exists, use that one. If none exists, no warning issued.

As for Mac, I think sticking to the OS convention is a sensitive thing to do. That is probably what best works with other tools. If a Mac user requires Linux-like behavior, then they can just spin up a Linux container ;)

[thaJeztah]

Thanks for your input! Yes, I think those suggestions (at least in broad lines) align with my train of thought.

For the "macOS" case, I'm still contemplating the "best of both worlds" approach; actual content can be stored in system "native" paths (~/Library/....), but (assuming Docker Desktop is installed) for Docker Desktop to create a symlink at $HOME/.config/docker, which could take a higher priority. Windows has it's own fair share of fun challenges though (with WSL2 being both "separate" and "connected" to the Windows side), so those will still take some thinking.

Re-designing configuration paths has been slightly upped in my teams backlog (we still have many other things, so no ETA yet), as it's a recurring topic, and with the introduction of many new components ((IDE) integrations, CLI plugins, contexts, CLI plugins keeping their own state) has become more problematic (e.g. situations where config-directories are mounted into containers, IDEs attempting to temporarily override configuration options).

I anticipate we'll start working on some rough / initial designs for this (including migration paths) in the not-too-distant future.