Start a machine from the image
When the import is done, create a machine from the snapshot that it saved. The snapshot stays, so you can start more machines from it later without importing the image again.node -v prints the image’s version, v16.20.2.
Import a private image
When the image is in a private registry, the import has to sign in to pull it. Pass the registry user with--registry-username, and give the password either in the INSTABOX_REGISTRY_PASSWORD
variable or on standard input with --registry-password-stdin. The password is used for the pull
and is not kept in the snapshot.
Import an image you built locally
An import pulls the image from a registry, so it cannot read an image that exists only in Docker on your computer. Push the image that you built to a registry first, and then import it by its registry name.Read the output of the image’s command
The image’sENTRYPOINT and CMD run as the instabox-image.service systemd unit, so their output
goes to the machine’s journal and not to your terminal. When you want to see whether the image’s
command started or why it failed, read the unit’s output with journalctl inside the machine.
--no-entrypoint, which
leaves the unit out.
How an import works
snapshot import starts a throwaway machine and pulls the image there with Docker. It lays the
image’s files over the machine’s own, and then restarts the machine to check that it still boots and
answers. Last, it saves the machine as a snapshot and deletes the throwaway machine. The throwaway
machine is an agent-browser one, and it counts while it runs.
What a machine from an image has
A machine from an image is still a machine, with the image laid on top. Where the two overlap, the image’s files win, and the parts that make the machine work stay.- The image’s files win: its programs, libraries,
/usr/local,/opt,/root,/home,/app, and its users. - Its
ENVreaches every session (exec, SSH, login shells), and the directories itsPATHadds come first. - Its
ENTRYPOINTandCMDrun as theinstabox-image.servicesystemd unit, in itsWORKDIR, as itsUSER(root when unset), restarted on failure. - What makes it a machine stays: systemd, sshd, sudo, the machine’s user (UID 1000, so the image’s
user with that ID, such as
node, is that user),/data, and the shared libraries the machine’s own programs load. /etc/instabox/image.jsonrecords the image’s reference, digest, and config.
Limits
- Only
linux/amd64images can be imported. - Ports that the image declares with
EXPOSEare not published. Publish them withinstabox port publish, as for any machine. See Public and private ports. - Snapshot limits apply (the free plan keeps ).
Init, apt, and the C library
Init, apt, and the C library
A machine runs systemd as its init. The image’s own init (tini, s6) is present but not run, only its
ENTRYPOINT and CMD. apt manages the machine’s own system. The image’s packages are there as
files, but apt cannot see or remove them. Debian and Ubuntu images, old ones too (Debian 10 buster),
run on the machine’s newer C library. Alpine (musl) images work best-effort.