atomic install --system documentation

[aveshagarwal]

If there is already documentation, please point me to that, I am looking for following things:

1. What different operations are done by atomic install and atomic install --system? I know that atomic install executes LABEL INSTALL from a dockerfile. What does --system specifically do, does it also execute LABEL INSTALL and does something on top of that? what is that?
2. What does --system expect? Is having /exports/config.json and /exports/.service in a container image enough to make it happy and to make it work with runc?
3. In general, it would be better to have something that explains how to create a container image that will work with "--system" flag of atomic install.

[aveshagarwal]

Got a one more question:

1. Lets say LABEL INSTALL already creates a systemd service file to run a container with docker. Would atomic install --system conflict with it?

[giuseppe]

this should be documented somewhere else, but for now, these slides can help to get an understanding of how system containers internally work: http://scrivano.org/static/system-containers-demo/

shortly, these are the most important operations done by atomic install --system --name=$NAME $IMAGE:

• a checkout of the image from the OSTree repository to /var/lib/containers/atomic/$NAME
• use /exports/{config.json, config.json.template} from the checked-out image rootfs to generate the OCI configuration.
• use /exports/service.template from the checked-out image rootfs to generate the OCI configuration.
• use systemctl to start the service

--system expects one of /exports/{config.json,config.json.template} for the OCI configuration, /exports/service.template and (used at the moment only to set default values in the template files) /exports/manifest.json

If any of these files is missing, then a default one is generated (for the runc configuration, runc spec is used, while the systemd default configuration file is hard coded in atomic)

As an example on how to create a system container, there is a simple Hello World image:

https://github.com/giuseppe/atomic-oci-containers/tree/master/hello-world

INSTALL is not executed by system containers, so that it won't collide with systemd service file exported from the image.

[aveshagarwal]

@giuseppe thanks.

[aveshagarwal]

@giuseppe Is it expected to modify config.json at run time to make any changes to container as needed after installation? If it is true, wouldn't be it better to move this config.json to somehere in /etc/ dir like /etc//config.json?

[giuseppe]

@aveshagarwal, differently than the systemd configuration file, that belongs to the container, the runc configuration file belongs to the deployment of the container. During an update, there are two different checkouts (/var/lib/containers/container.0 and /var/lib/containers/container.1) and each of those could have a different configuration file. That will allow us to support a rollback to the previous version if needed.

Now that I think more of it, it would probably make sense to keep the systemd file as well under the deployment and have only a symlink under /etc/systemd/system, even though it is not supposed to change often, it can still be useful to have a better versioning of it.

Would a symlink to the configuration file /etc/containers/container.json -> /var/lib/containers/container/config.json? (not having the .0 or .1 ending in the path points directly to the deployment currently in use)

[rhatdan]

Cleaning up issues.

@aveshagarwal @giuseppe Should this remain open?

[giuseppe]

actually I've tried my proposed solution but it doesn't work as systemd doesn't like to have a symlink instead of a file under /etc/systemd/system. I have started looking into detecting changes that are manually made by the user, so that update will detect them and won't wipe them. It is somehow related to this issue.