Add an initial Colima guide

[deviantintegral]

The New Solution/Problem/Issue/Bug:

It's time to document what we've learned at https://github.com/drud/ddev/issues/3208

How this PR Solves The Problem:

This PR adds a "from scratch" guide for using colima instead of Docker Desktop.

Manual Testing Instructions:

Follow the instructions in this doc!

[deviantintegral]

I was going to document xdebug and host.docker.internal, but I need to followup on https://github.com/lima-vm/lima/pull/457/files first.

[rfay]

It's great, but I'm working on https://github.com/drud/ddev/pull/3445 which will make import-db, export-db and hopefully snapshot features work as well. And I wouldn't be surprised if we can just get this into an experimental topic in ddev itself. Also, you can make lots of things work across DOCKER_HOST with this technique, colima is just one example.

[deviantintegral]

Well, this is weird. I just rebooted for the macOS 12.1, and while docker at the CLI works, ddev throws:

$ ddev status
Failed to describe project(s): Get "http://unix.sock/containers/json?all=1&filters=%7B%22label%22%3A%5B%22com.ddev.site-name%3Ddrupal%22%2C%22com.docker.compose.service%3Dweb%22%5D%7D": dial unix /var/run/docker.sock: connect: no such file or directory

I actually uninstalled Docker Desktop earlier, so it's no longer in play. After running colima start I see:

$ docker context ls
NAME       DESCRIPTION                               DOCKER ENDPOINT                            KUBERNETES ENDPOINT   ORCHESTRATOR
colima *   colima                                    unix:///Users/andrew/.colima/docker.sock
default    Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                                      swarm

And if I symlink /Users/andrew/.colima/docker.sock to /var/run (using sudo, the directory isn't writable by a normal macOS user) ddev works.

So... perhaps I symlinked a month or two ago and forgot? I hadn't rebooted for a while. But, I would have thought that would have been brought up early in your testing of colima too.

[rfay]

I also just upgraded to macOS 12.1 (moments ago). I'm not seeing general problems. Are you saying you're having problems just with colima, or in general with Docker Desktop?

I just exited Docker Desktop and started colima and had no trouble with it. However, I'm using the default docker context, I hadn't used docker context to switch back and forth with colima previously, will look forward to learning about that technique.

[rfay]

BTW, one of the awesome things about colima is that we'll be able to use Github Actions to test it, even on macOS I think, since we don't have the crazy problem of how to install Docker Desktop.

[deviantintegral]

It looks like ddev is broken in colima HEAD, soon to be 0.3.0.

https://github.com/abiosoft/colima/pull/40 switched to using docker contexts instead of hardcoding the socket, which I think is a good improvement. However, I guess I didn't realize that ddev doesn't actually use contexts itself.

As a workaround, we can manually add the symlink to the socket. However, I think it would be smoother if ddev respected the active docker context.

@rfay would you like me to update the docs with that workaround so we can merge as is, or would you rather leave this open, add context support in ddev, and merge this after?

[rfay]

Shoot, the problem is that neither docker's go api nor docker-go respect contexts. Glad you caught this. I'll have to take a look at what the options are for respecting contexts. It's not likely to be pretty, but should be do-able.

I'd prefer to keep this open for now, please feel free to push new edits into it.

[deviantintegral]

docker context inspect at least gives JSON output of the currently active context. No idea if that's considered to be a stable API though.

$ docker context inspect

[
    {
        "Name": "colima",
        "Metadata": {
            "Description": "colima"
        },
        "Endpoints": {
            "docker": {
                "Host": "unix:///Users/andrew/.colima/docker.sock",
                "SkipTLSVerify": false
            }
        },
        "TLSMaterial": {},
        "Storage": {
            "MetadataPath": "/Users/andrew/.docker/contexts/meta/f24fd3749c1368328e2b149bec149cb6795619f244c5b584e844961215dadd16",
            "TLSPath": "/Users/andrew/.docker/contexts/tls/f24fd3749c1368328e2b149bec149cb6795619f244c5b584e844961215dadd16"
        }
    }
]

[rfay]

Yeah, the problem is that contexts are a level higher than the docker api, which assumes it knows who it's talking to. I'll take a look at the docker cli code to see how it does it.

[abiosoft]

Shoot, the problem is that neither docker's go api nor docker-go respect contexts. Glad you caught this. I'll have to take a look at what the options are for respecting contexts. It's not likely to be pretty, but should be do-able.

As a last resort, there is the DOCKER_HOST environment variable.

[rfay]

Right, I'm pretty sure DOCKER_HOST would work right now.

[rfay]

• https://github.com/drud/ddev/pull/3452 addresses this in a fairly sad way.

[deviantintegral]

Nice! It's better than not working all.

Unfortunately, my laptop just bit the dust and it's 7-10 days to repair. I'm stuck on Windows in the meantime, so I won't be able to pick up any testing until January.

[rfay]

Thanks for all your work on this! You should be able to test it in wsl2 though :)

[rfay]

It may be that just using DOCKER_HOST will be a better answer than this PR. I'll have to take a look at the test failures and see how deep I got myself in trouble.

[rfay]

Colima is now officially supported in HEAD, brew unlink ddev && brew install drud/ddev/ddev --HEAD, see https://ddev.readthedocs.io/en/latest/users/docker_installation/#macos-installation-colima

Thank you so much for pioneering this, and looking forward to your experiences, feedback, improvements.