Topic: Find a good and non-confusing home for the remaining monolith

As explained in https://github.com/moby/moby/issues/32871,

https://github.com/moby/moby will be the home of the moby tool.
Today we have the code of the legacy “docker engine” (a monolith to be split out in multiple components) at the root and it’s very confusing.

After some discussion during the daily moby meetings, we decided to experiment with a internal reorganization of the repository by moving most of the “docker engine” related directories into a subdirectory (monolith in this example).

This would leave the repository with, simply put 6 folders

  • api # cannot be moved yet, because it’s used externally
  • client # cannot be moved yet, because it’s used externally
  • moby # the moby tool
  • monolith # the code where “docker engine” lives, to be split out and eventually will disappear
  • pkg # cannot be moved yet, because it’s used externally, but @dnephin is leading the effort on that.
  • vendor # vendoring

@cpuguy83 started working on it here: https://github.com/moby/moby/pull/33022

Besides a couple of CI issues, it’s working.

re: CI issues

The CI is making assumptions about where things are that it should not.
I’ve tried to work around this by making copies as needed in both the old location and the new so that CI is fully operational on the PR (and anything after it’s merged until the CI scripts are updated), but sadly not everything can be fixed in the repo itself but rather requires updating CI once it is merged.

At the moment the as mentioned by @vieux everything except for a few dirs are moved into /monolith in the repo.

It should be the home for:

  1. the moby tool
  2. the standard library of components (something that can be built into a container)
  3. the standard library of assemblies (something that can be assembled from a yaml blueprint and a library of components)

A good point of comparison is homebrew. It’s a tool, and it’s a collection of packages. Homebrew is more mature and has spun out its library into a separate repository. But I propose keeping our library in the main repository for now, until the project structure stabilizes and we are comfortable with less agility.

Agreed.

Can we please decide on the final project structure before we make intermediate changes like this internal reorganization? Otherwise I worry we will discover that the change wasn’t as intermediate as we hoped, and we will be stuck in an awkward middle state that is still confusing, and is not what we want.

Here’s a strawman to get the discussion started. It’s probably a bad idea, but hopefully it can trigger conversations that will lead us to good ideas.

  1. We move the monolith into pkg. That means we make it a Go package (or a collection of Go packages). That’s already 99% the case. If there is too much intelligence in the main() to extract, then we wrap that main into a convenience function in the package. The point is, we are moving away from offering a monolithic daemon called dockerd, and the sooner the source code structure reflects that, the better.

  2. We create a reference assembly that reproduces the backend configuration previously known as “the docker engine for Linux”. In addition to containerd, this assembly would include the 4 or 5 daemons which currently implement engine. Of course the docker name would be removed, and we would discourage downstream distributions from shipping this assembly as-is. It would act more as a contrib: an example of how you can use Moby to build a Docker equivalent. As we make progress breaking up the monolith into more discrete components, the assembly can be updated to continue performing the same function - only with more components.

So, that’s my bad idea to help find a good idea. wdyt?

The other coin of this, is that it will take us an indefinite amount of time to decide on the final structure of the project and in the mean time people will associate moby/moby as being the engine (I mean the majority of the top files let you believe so atm and most of the .md regarding the project are docker/engine specific atm).

Moving it into an intermediate repo to clean up the top level solve this. And I don’t see how that would led us to never move out of it.

I’m not ecstatic at the idea of having to maintain the current engine code as a library , its design doesn’t fit a library. The future broken component would/should be better candidates.
eat_smile:.

As an alternative, I wouldn’t mind removing the main, moving it to docker/cli or somewhere else and name the rest legacy-engine, while making it clear that it’s not a supported package per se.

This I agree, a reference assembly is needed to showcase and explain the goal of moby in more practical details. Although, I think it depends on the moby tool learning how to make deb/rpm :slight_smile:. It will be quite exiting once it does!

1 Like

I agree with @mlaventure here. I don’t buy that moving it now will keep us from doing the work to break it up.
One of the reasons we wanted to move it right away is so we can bring the moby tool in and make it the focus of the repo.

One added benefit of moving it now is we get to see where the CI configuration is making bad assumptions about how to setup the testing env. Right now there’s lots of hard-coded things and in many places (I’ve found) it’s not using the Makefile.

These two confuse me. They look like something that belongs in LinuxKit and I don’t believe that’s moving over. How do the above differ from what’s in linuxkit/linuxkit/pkg.

The majority of linuxkit/linuxkit/pkg needs to move to Moby. The fact that it’s still in Linuxkit is an artifact of how Linuxkit was created (spun out of Moby).

The exception will be components that are directly tied to the Linux host. For example, a userland wireguard component which specifically requires a LinuxKit’s wireguard-enabled kernel would belong in LinuxKit. That leaves open the question of how to manage components which stay in LinuxKit.

A good comparison for LinuxKit is the original lxc project (emphasis on original). The lxc project was a kernel-centric project: its purpose was to contribute container capabilities into the kernel. Along the way, it also produced userland tools to demonstrate the kernel capabilities. Once all kernel contributions were merged, the userland tools took a life of their own.

LinuxKit is similar in structure to the original lxc project: it’s a kernel-centric project (produce a secure, lean, portable Linux subsystem) which happens to carry userland components. These userland components should be easy to incorporate into Moby.

My rationale for the things that should stay in linuxkit/linuxkit/pkg is whether you need them if you were running an assembly not on bare metal. Things like dhcp and sysfs and ntpd are needed to get things running, and are already part of (say) Debian. So they should stay in linuxkit.

So the things that should move out of linuxkit are the temporary docker-ce package, runc and containerd, but I think all the rest should stay (sshd is a bit of an edge case; its more or less a dev container).

(there will be some more pieces that should move to moby though, as we rebuild editions on linuxkit)

That makes sense. The problem right now is not so much that LinuxKit has packages; it’s that Moby doesn’t have packages at all; this would be like (in my example) the lxc project having RPMs for its userland tools, but without RPMs existing anywhere else.

We need to urgently give Moby more of the features of a distro - a new kind of distro, but a distro nonetheless. This in turn will make things more clear. And clarity is what we need most right now.

Thanks, consider me less confused on where you want to be. Now back to figuring out how to get there.

My own gut reaction is to keep the moby tool and docker engine as separate repos. Whether that means renaming moby/moby to get the tool to the new name, or leaving the tool in a different repo, it doesn’t bother this user either way. I’d just prefer not to have the code, issues, and PRs of two distinct projects in the same namespace.

bmitch3020
May 12

Thanks, consider me less confused on where you want to be. Now back to
figuring out how to get there.

Ok :slight_smile:

My own gut reaction is to keep the moby tool and docker engine as
separate repos. Whether that means renaming moby/moby to get the tool to
the new name, or leaving the tool in a different repo, it doesn’t bother
this user either way. I’d just prefer not to have the code, issues, and PRs
of two distinct projects in the same namespace.

Yes that is a valid argument in favor of separating out the engine (aka
“the monolith”) into its own repo.

There are also arguments in favor of keeping it in place. Some of these
arguments are:

  • We want to split up the engine into distinct components, so eventually
    (let’s say within 9-12 months) that repository would go away.
  • We need to create one more name for a thing, in a time where there are
    lots of new things with lots of new names.
  • We very recently moved docker/docker to moby/moby, which was a disruption
    to contributors. Another move so shortly afterwards could make things worse.
  • Because there is confusion between “Docker platform” and “Docker
    container engine”, this new repo might be interpreted as “Docker platform
    without the brand”, which implies a promise of feature parity and interface
    compatibility with Docker… a promise we don’t want to make. I also worry
    that a well-intentioned distro packager will understand the engine repo as
    a drop-in replacement for the docker package… Which would be a mistake.

Note that these arguments don’t necessarily represent my opinion. I’m still
working on forming a final opinion :slight_smile:

shykes https://forums.mobyproject.org/u/shykes
May 12

justin: shykes:

shykes:

The majority of linuxkit/linuxkit/pkg needs to move to Moby. The fact that
it’s still in Linuxkit is an artifact of how Linuxkit was created (spun out
of Moby).

My rationale for the things that should stay in linuxkit/linuxkit/pkg is
whether you need them if you were running an assembly not on bare metal.
Things like dhcp and sysfs and ntpd are needed to get things running, and
are already part of (say) Debian. So they should stay in linuxkit.

So the things that should move out of linuxkit are the temporary docker-ce
package, runc and containerd, but I think all the rest should stay (sshd is
a bit of an edge case; its more or less a dev container).

The majority of linuxkit/linuxkit/pkg needs to move to Moby. The fact that
it’s still in Linuxkit is an artifact of how Linuxkit was created (spun out
of Moby).

That makes sense. The problem right now is not so much that LinuxKit has
packages; it’s that Moby doesn’t have packages at all; this would be like
(in my example) the lxc project having RPMs for its userland tools, but
without RPMs existing anywhere else.

We need to urgently give Moby more of the features of a distro - a new
kind of distro, but a distro nonetheless. This in turn will make things
more clear. And clarity is what we need most right now.

I think candidates would be docker-ce, runc and containerd, though the
latter two are kinda essential to LinuxKit but will also likely be used
outside LinuxKit. The packages should probably also move to a different hub
repo.

Where should we move packages to?

For this, I’d say renaming to a final location now would lessen any pain 9-12 months from now when whatever is left gets renamed to $gRPC_multiplexer_project_name. If we can find a good name for that 12 month move now, that would be even better for keeping the issues, pr’s etc, with the engine code. If not, at that 12 month point, 95% of those issues will need to move to another project, but they’ll be in a single repo to sort through rather than intermixed with everything in the moby tool repo.

I’m less confused by lots of new names. Reusing the same name for multiple things is what confuses me. See this blog post from me for a little more background. The new name could be something like moby/ce or moby/engine and make more sense to those not familiar with moby.

I completely understand. We can’t undo what happened before so I’m going to take the economics view of a sunk cost. Without considering the past, starting from where we are today, what’s the best option? The only additional thing I’d recommend is putting out a post saying “in 5 days, we’re moving moby/moby to it’s final home xyz” so it’s not a surprise.

As long as we don’t call it moby/docker-ce, I think the only other thing to do is to have a good readme that lays out exactly what you just said. It’s certainly a point I was missing before now.

bmitch3020 https://forums.mobyproject.org/u/bmitch3020
May 12

Solomon_Hykes:

There are also arguments in favor of keeping it in place. Some of these
arguments are:

  • We want to split up the engine into distinct components, so eventually
    (let’s say within 9-12 months) that repository would go away.

For this, I’d say renaming to a final location now would lessen any pain
9-12 months from now when whatever is left gets renamed to
$gRPC_multiplexer_project_name. If we can find a good name for that 12
month move now, that would be even better for keeping the issues, pr’s etc,
with the engine code. If not, at that 12 month point, 95% of those issues
will need to move to another project, but they’ll be in a single repo to
sort through rather than intermixed with everything in the moby tool repo.

The only way to avoid an issue migration would be to rename the current
moby/moby to the new monolith repo, right? But that would cause more
rename headaches.

So we need to choose from two ways to create a new monolith repo:

Option 1: rename. Pro: no issue migration. Con: rename headaches.
Option 2: create fresh. Pro: no rename headaches. Con: issue migration (but
not intermixed with moby tool issues as you say).

I think I prefer option 2. Issue migration is less painful than renaming.
And those issues need a serious manual sort anyway. So we will pay that
cost regardless.

  • We need to create one more name for a thing, in a time where there
    are
    lots of new things with lots of new names.

I’m less confused by lots of new names. Reusing the same name for multiple
things is what confuses me. See this blog post from me
https://boxboat.com/2017/05/12/moby-inception/ for a little more
background. The new name could be something like moby/ce or moby/engine and
make more sense to those not familiar with moby.

I agree that creating a new name is much easier than redefining an existing
name.

  • We very recently moved docker/docker to moby/moby, which was a
    disruption
    to contributors. Another move so shortly afterwards could make things
    worse.

I completely understand. We can’t undo what happened before so I’m going
to take the economics view of a sunk cost. Without considering the past,
starting from where we are today, what’s the best option? The only
additional thing I’d recommend is putting out a post saying “in 5 days,
we’re moving moby/moby to it’s final home xyz” so it’s not a surprise.

Before anything, the most urgent is to switch to facade URLs for go
packages. We can do this right now. Tibor, Victor: what’s the status on
that? As soon as facade URLs are in place everywhere, the number of
affected repos will stop growing.

Then, yes, we should clearly announce that 1) facade URLs are the
recommended official way to consume, available now; and 2) there is a X
days grace period before the old URLs are disabled.

  • Because there is confusion between “Docker platform” and “Docker
    container engine”, this new repo might be interpreted as “Docker
    platform
    without the brand”, which implies a promise of feature parity and
    interface
    compatibility with Docker… a promise we don’t want to make. I also
    worry
    that a well-intentioned distro packager will understand the engine
    repo as
    a drop-in replacement for the docker package… Which would be a
    mistake.

As long as we don’t call it moby/docker-ce, I think the only other thing
to do is to have a good readme that lays out exactly what you just said.
It’s certainly a point I was missing before now.

I agree. Victor: can you add this to the task list?

My favorite option is to create a new repository for the engine monoith,
with a fresh new name, and start the migration process as described here
ASAP.

I have an idea for a name :slight_smile:

Thoughts?

Some question.

It sounds like the “rename” option is “rename the github repo” as well as change the golang import path.

Is the “create fresh” option to create a new github repo (no stars, watchers, issues or PRs) and git push the current master of moby/moby to this repo? This requires changing the golang import path as well, right?

What is “rename headaches” in the pro/con list? I don’t think I understand why option 2 doesn’t have the same rename headaches as option 1, and that must be because I’m not understanding what they are.

The rename headaches comes from the fact that docker/docker was already renamed to moby/moby. One more rename will cause headaches. Especially if we also want moby/moby to be the home of the tool

I spoke with @mlaventure and it sounds like the headache that is being described here is the following:

If we were to rename the github repo to some other name, then move moby/tool -> moby/moby the redirect from both docker/docker and moby/moby to the new repo would be broken.

Does that match everyone’s understanding of “rename headaches” ?

What’s not clear to me is how this is any different than creating a new repo? In both cases there is no redirect from docker/docker to the new monolith. We could rename it back to docker/docker then immediately to the new repo, which would at least give us a redirect from docker/docker to the new monolith repo, but would not for moby/moby which is probably ok because it has only existed there for a short time, and the golang imports are still docker/docker.

So I’m still not clear on how option 2 removes the rename headaches. It seems like the only different is where the stars/issues/PRs end up. Either way we have to do issue triage to split up the issues.

AIUI a bunch of people who were at the recent (in March?) maintainerati conference (not me :-/) have links with people at GH who we can talk to about this sort of thing. I think @avsm, @amir and @tiborvass were there among others.

Given that we should be asking them what can be done to alleviate the rename headaches – for all we know it would be trivial for the docker/docker redirect to be changed to point to moby/wibble at any time, if we just ask/coordinate.

Also, irrespective of which option we are leaning towards and the renaming/redirecting problems we should already be speaking to GH about this IMHO.

I do have some people that I can probably contact to ask what options there are (actually had a call scheduled today with GitHub on another matter, but that one got cancelled last minute)

If we know what questions we have, I can try reaching out to them, things that come to mind;

  • relocate issues separate from pull requests (e.g. move all issues from moby/moby to docker/for-linux)
  • fix redirects if we move the monolith (possibly redirect docker/docker to moby/the-monolith-repo)
  • anything else?
2 Likes

I’ve had both of those done via requests to GitHub support in the past, but it would be really useful to run the whole plan past someone at GitHub to check that there isn’t a fundamental flaw in the redirect scheme. Perhaps find out if there is a developer advocate willing to look at the whole picture, @thaJeztah?