improving docker support with various fixes to support image building

packages/nopy/docs/DOCKER.md

@@ -5,7 +5,7 @@ This guide explains how to set up a local Docker container to test `nopy` deploy
 ## Prerequisites
 
 - Docker installed and running on your machine.
-- `nopy` installed and linked (see [README.md](./README.md)).
+- `nopy` installed and linked (see [README.md](../README.md)).
 
 ## 1. Setup SSH Key (Important)
 
@@ -80,3 +80,48 @@ To stop and remove the container:
 ```bash
 docker rm -f nopy-test-container
 ```
+
+## Building an image instead of targeting a container
+
+The `@docker` connector reads its identifier two ways, and the difference is
+the whole feature:
+
+| Host                  | What pyinfra does                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| `@docker/<container>` | runs against that container and leaves it running — the flow above                     |
+| `@docker/<image>`     | starts a throwaway container, deploys into it, `docker commit`s it, prints the new image ID, removes the container |
+
+It looks for a matching container first, so nothing distinguishes the two at the
+prompt: pick `docker` at host selection and enter either an existing container
+or an image reference such as `ubuntu:24.04`.
+
+```
+$ nopy install
+? Select host from inventory  docker
+? Specify docker container name/id, or an image to build from:  ubuntu:24.04
+...
+--> docker build complete, image ID: 39b782da6859
+$ docker tag 39b782da6859 myapp:1.0
+```
+
+Two things the connector cannot do, both worth knowing before treating this as a
+Dockerfile replacement. The commit is untagged, so the image exists only as an
+ID until you tag it; and it carries the base image's metadata unchanged —
+`CMD`, `ENTRYPOINT`, `ENV`, `EXPOSE` have no equivalent in a cube. When either
+matters, own the container yourself and commit deliberately:
+
+```bash
+cid=$(docker run -d ubuntu:24.04 sleep infinity)
+nopy install            # host: docker → paste $cid at the prompt
+docker commit --change 'CMD ["/usr/sbin/sshd","-D"]' "$cid" myapp:1.0
+docker rm -f "$cid"
+```
+
+There is no `--host` flag; for an unattended build put the identifier in a
+session file's `hosts` array (as `example.nopysession.json` does) and replay it
+with `nopy install -l <file>`.
+
+Note also that an image target starts from a fresh container every run, so every
+cube reports changes every time — idempotence only shows up when you re-run
+against a container id. And there is no init system in a plain container, so
+service-level cubes still need the `--privileged` systemd setup above.

packages/nopy/example.nopysession.json

@@ -8,7 +8,7 @@
       }
     }
   ],
-  "hosts": ["@docker/nopy-test-ubuntu"],
+  "hosts": ["@docker/nopy-test-container"],
   "env": {
     "KEY_DIR": "../../vault/tmp"
   },

packages/nopy/src/nopy.prompts.ts

@@ -117,6 +117,17 @@ export async function PasswordSelection(username: string): Promise<string> {
   return password;
 }
 
+/**
+ * Prompts for the deployment target, normalising the built-ins into the host
+ * strings pyinfra's connectors expect.
+ *
+ * The docker branch takes either identifier the connector accepts, and they
+ * mean very different things: a **container** name or id is mutated in place
+ * and left running, while an **image** reference makes pyinfra start a
+ * throwaway container, apply the deploy, commit the result as a new image and
+ * print its id. Only the connector can tell the two apart — it looks for a
+ * matching container first — so the prompt does not try to.
+ */
 export async function HostSelection(hosts: string[]): Promise<string> {
   const selectedHost = await inquirer.prompt([
     {
@@ -140,13 +151,14 @@ export async function HostSelection(hosts: string[]): Promise<string> {
     },
     {
       type: 'input',
-      name: 'dockerContainer',
-      message: 'Specify docker container name:',
-      when: (answers) => answers.host === 'runtime:docker',
+      name: 'dockerTarget',
+      message: 'Specify docker container name/id, or an image to build from:',
+      when: (answers) => answers.host === 'docker',
+      validate: (value: string) => value.trim().length > 0 || 'Required',
     },
   ]);
   if (selectedHost.host === 'vagrant') return `@vagrant/${selectedHost.vagrantVM}`;
-  if (selectedHost.host === 'runtime:docker') return `@docker/${selectedHost.dockerContainer}`;
+  if (selectedHost.host === 'docker') return `@docker/${selectedHost.dockerTarget.trim()}`;
   return selectedHost.customHost ?? selectedHost.host;
 }
 

packages/nopy/tests/prompts.test.ts

@@ -199,11 +199,32 @@ describe('HostSelection', () => {
   });
 
   it('prefixes a docker container', async () => {
-    inquirerPrompt.mockResolvedValue({ host: 'runtime:docker', dockerContainer: 'box' });
+    inquirerPrompt.mockResolvedValue({ host: 'docker', dockerTarget: 'box' });
 
     await expect(HostSelection([])).resolves.toBe('@docker/box');
   });
 
+  it('prefixes a docker image reference the same way', async () => {
+    inquirerPrompt.mockResolvedValue({ host: 'docker', dockerTarget: 'ubuntu:24.04' });
+
+    await expect(HostSelection([])).resolves.toBe('@docker/ubuntu:24.04');
+  });
+
+  it('trims the docker identifier', async () => {
+    inquirerPrompt.mockResolvedValue({ host: 'docker', dockerTarget: '  ubuntu:24.04 ' });
+
+    await expect(HostSelection([])).resolves.toBe('@docker/ubuntu:24.04');
+  });
+
+  it('rejects an empty docker identifier', async () => {
+    inquirerPrompt.mockResolvedValue({ host: 'web-1' });
+
+    await HostSelection([]);
+
+    expect(question('dockerTarget')?.validate('  ')).toBe('Required');
+    expect(question('dockerTarget')?.validate('ubuntu:24.04')).toBe(true);
+  });
+
   it('gates the follow-up questions on the chosen host', async () => {
     inquirerPrompt.mockResolvedValue({ host: 'web-1' });
 
@@ -213,8 +234,12 @@ describe('HostSelection', () => {
     expect(question('customHost')?.when({ host: 'web-1' })).toBe(false);
     expect(question('vagrantVM')?.when({ host: 'vagrant' })).toBe(true);
     expect(question('vagrantVM')?.when({ host: 'web-1' })).toBe(false);
-    expect(question('dockerContainer')?.when({ host: 'runtime:docker' })).toBe(true);
-    expect(question('dockerContainer')?.when({ host: 'web-1' })).toBe(false);
+    // The regression: the gate compared against the `runtime:docker` *cube id*,
+    // so picking `docker` from the list skipped this question entirely and the
+    // host came back as the literal string `docker`.
+    expect(question('dockerTarget')?.when({ host: 'docker' })).toBe(true);
+    expect(question('dockerTarget')?.when({ host: 'runtime:docker' })).toBe(false);
+    expect(question('dockerTarget')?.when({ host: 'web-1' })).toBe(false);
   });
 });