Develop a repository on a container
Found this helpful? Share it:
Found this helpful? Share it:
A container gives a repository somewhere to live that idapt can back up, move
and restore. This is the shortest path from an empty container to npm test
running against your own checkout, plus the four places people get stuck.
| What | Survives a move or a restore |
|---|---|
| Files in a declared volume, including your clone | Yes |
| The image, so the toolchain comes back | Yes |
| A Compose stack's own images | Yes, they are captured with its volumes |
| Files written outside a volume | No |
A scratch container itself | No, it is deleted at teardown and never backed up |
Put the clone in a volume. A container with no volume can still be backed up for its image, but the working tree is gone the moment it is recreated.
/workspace.Use lifetime_class: service for a container whose checkout you care about.
scratch is for a throwaway experiment: it is deleted when its computer is torn
down, and idapt refuses to back it up.
A working checkout has three layers, and they come from three different places. Confusing them is the usual reason a container "has no node" or "has no docker".
| Layer | What it is | Where it comes from |
|---|---|---|
| Base image | The OS and the big tools: Docker in docker, Node in node | The image the container is created with |
| System setup | apt and curl installers: k3d, a database client, a compiler | A setup script kept in the repository |
| Language dependencies | node_modules, a virtualenv, a Go module cache | npm ci, pip install, go mod download, per clone |
node:22-alpine installs node and nothing else. It does not
install Docker, k3d or a database server. Those belong to the setup script.
setup.sh in the repository and commit it. Guard every install with a check, so running it twice is safe.If package.json declares packageManager while the lockfile
is pnpm-lock.yaml, corepack-aware tooling picks pnpm and fails with
ERR_PNPM_UNSUPPORTED_PROTOCOL. Call npm ci explicitly in the script.
Prefer one approach or the other: a setup script replaces what a development Dockerfile would install. If the repository already has a Dockerfile that describes its toolchain, building it inside a dind container and running that image is the faithful option, it is just slower on a fresh box than running the script.
A devcontainer.json describes a development environment for an editor, and the
cloud-computer dev lane executes a supported subset of it. When a computer is
created with a repository, it clones the repo, reads
.devcontainer/devcontainer.json or devcontainer.json, builds or pulls the
image, runs the container, and runs postCreateCommand inside it. Keys outside
the subset are listed as ignored in the operation notes, never silently dropped.
| In devcontainer.json | What the dev lane does |
|---|---|
image | Runs that image |
build.dockerfile and build.context | Builds it on the machine and runs the result |
containerEnv | Passes each value as container environment |
remoteEnv | Passes each plain value the same way; a value that references a containerEnv variable is reported, not expanded |
forwardPorts | Publishes each port |
postCreateCommand | Runs it once, in workspaceFolder, as remoteUser |
remoteUser | Runs postCreate as that user |
workspaceFolder | Mounts the clone there and starts the container there |
mounts (named volumes) | Mounts type=volume entries; bind mounts are refused |
features | Not executed. docker-in-docker needs a container with the dind capability |
On a container you create yourself, none of this runs for you: read the file as
the instruction sheet and do the same steps, or let the dev lane do them. Look
at the devcontainer first, then at .env.example, then at the Dockerfile, then
at the README.
A single command run through the agent surface is cut off after about a minute. A build that takes longer is not failed, it is abandoned, and the process may keep running on the box with nothing reading its output.
For anything longer than a minute, do one of these instead:
The second pattern looks like this: start the command with its output redirected to a file and its process detached, then read the tail of that file on each poll until the exit status appears. A build that is still running shows new lines; a finished one stops growing.
Some repositories build images as part of their tests. The dind capability
grants the privilege a nested daemon needs. It does not install one: the image
has to carry Docker already, so docker:27-dind works and a plain node:22 or
alpine does not (it answers docker: not found with the capability granted).
A Compose stack declares privileged: true for its build service only when the
container carries dind, and it asks for that when the stack is created:
idapt container compose-up --capabilities dind. Without the capability the
platform refuses the document before it reaches the machine.
A nested daemon listens on port 2375 without authentication. Anything that can reach that URL can start containers on the box. Keep the exposure private, or run the daemon with TLS on 2376 and client certificates. The port list says which of the two you are looking at.
A dind container's image cache is large and reproducible, so it is excluded from backups by default. Everything else in the volume set is captured.
A nested k3d cluster runs inside a privileged docker:27-dind container. Verified on a
standard.xl cloud computer: k3d cluster create created a
cluster whose node reached Ready in about 40
seconds, with no run flags beyond the capability.
capabilities: ["dind"], a 1 GiB shm and at least 8 GiB of memory, a cluster plus a build is comfortable there.docker:27-dind image is Alpine and ships neither curl, bash nor node.Ready.This is the check to run before a repository depends on the capability: create the
container, run k3d cluster create and confirm the node reports Ready. If it does
not, the machine cannot host a nested cluster and the container is the wrong shape.
Some workloads need the kernel, not just the filesystem: an Android emulator needs
/dev/kvm, and Elasticsearch needs vm.max_map_count raised. Neither is a
container creation field. The dind container is the way in: inside it you own a
real Docker daemon, so --device and --sysctl are yours to pass.
dind capability and a docker:27-dind image.ls -l /dev/kvm inside the container. A device the machine does not have cannot be passed through.docker run --device /dev/kvm ..., or docker run --privileged --sysctl vm.max_map_count=262144 ... for a setting that is not namespaced.vm.max_map_count is a global kernel setting, so a privileged nested daemon is the
only place to set it without host access. What runs inside that nested daemon is
not part of the container's backup: the image cache is excluded, and the nested
volumes are not captured.
service container is stopped, backed up and left unplaced.A backup pauses the container while the copy is taken. That is deliberate: a copy taken from a running database is not reliably restorable. Expect a few seconds of downtime per backup, proportional to how much has to be written.
Related articles
Containers
Run a Docker image or a Compose stack on your computers, and know what survives a restart.
Compose files
Bring your own Compose file, and fix the few settings idapt refuses.
Backup and restore
What a backup captures, how long it is kept, and the difference between restore and rebuild.
Give a container a secret
Bind a credential by name so the value never appears in a file, a backup, or a chat.
| Command | What it does |
|---|---|
idapt container list | List a workspace's containers. |
idapt container get | Get one container. |
idapt container create | Create a container from an image. |
idapt container compose-up | Create a container from a Compose document. |
idapt container run | Build from a Dockerfile and run it. |
idapt container update | Rename or re-describe a container. |
idapt container delete | Delete a container. |
idapt container up | Start a container. |
idapt container down | Stop a container. |
idapt container restart | Restart a container. |
idapt container rebuild | Rebuild or re-pull the image, keeping volumes. |
idapt container compose-get | Get the container's Compose document. |
idapt container compose-set | Replace the container's Compose document. |
idapt container logs | Read a container's logs. |
idapt container exec | Run a command inside a container. |
idapt container ports | List a container's ports. |
idapt container port-open | Expose a container port at a URL. |
idapt container port-close | Stop exposing a container port. |
idapt container port-make-public | Make an exposed container port PUBLIC (unauthenticated). Subscriber-only + human-approved + time-boxed. |
idapt container port-revoke-public | Revoke a container port's public grant - it reverts to authenticated access. |
idapt container backup | Back up a container's volumes and image. |
idapt container restore | Restore a container from a backup. |
idapt container backups | List a container's backups. |
idapt container migrate | Move a container to another computer. |
idapt container events | A container's activity feed. |
idapt container runtime | Docker runtime status on a computer. |
Was this helpful?