128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
# Testing Nopy with Docker
|
|
|
|
This guide explains how to set up a local Docker container to test `nopy` deployments using the provided `Ubuntu-24LTS.Dockerfile` and `example.nopysession.json`.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker installed and running on your machine.
|
|
- `nopy` installed and linked (see [README.md](../README.md)).
|
|
|
|
## 1. Setup SSH Key (Important)
|
|
|
|
The provided `Ubuntu-24LTS.Dockerfile` contains a hardcoded public SSH key. Before building, you **must** replace it with your own public key to allow SSH access (if needed) or ensure `pyinfra` can connect if it uses SSH transport.
|
|
|
|
1. Open `Ubuntu-24LTS.Dockerfile`.
|
|
2. Locate the line starting with `echo "ssh-ed25519 ...`.
|
|
3. Replace the key string with the content of your own public key (usually `~/.ssh/id_ed25519.pub` or `~/.ssh/id_rsa.pub`).
|
|
|
|
```dockerfile
|
|
# Example replacement
|
|
RUN mkdir -p /home/testuser/.ssh && \
|
|
echo "YOUR_PUBLIC_KEY_HERE" >> /home/testuser/.ssh/authorized_keys && \
|
|
...
|
|
```
|
|
|
|
## 2. Build the Docker Image
|
|
|
|
Run the following command from the `packages/nopy` directory:
|
|
|
|
```bash
|
|
docker build -f Ubuntu-24LTS.Dockerfile -t nopy-test-ubuntu .
|
|
```
|
|
|
|
## 3. Run the Container
|
|
|
|
Start the container in the background. We explicitly name it `nopy-test-container` because the `example.nopysession.json` is configured to target this specific container name.
|
|
|
|
```bash
|
|
docker run -d \
|
|
--name nopy-test-container \
|
|
--privileged \
|
|
-p 2222:22 \
|
|
nopy-test-ubuntu
|
|
```
|
|
|
|
- `--name nopy-test-container`: Matches the host defined in `example.nopysession.json`.
|
|
- `--privileged`: Required for some system-level operations (like `criu` or service management) if tested.
|
|
- `-p 2222:22`: Maps the container's SSH port to local port 2222 (optional, allows manual SSH connection).
|
|
|
|
## 4. Deploy using Nopy
|
|
|
|
Now you can run the example session. Nopy uses `pyinfra`'s `@docker` connector to communicate directly with the container, so SSH keys are not strictly required for the *deployment* itself, but the session is configured to simulate a realistic environment.
|
|
|
|
```bash
|
|
nopy install -l example.nopysession.json
|
|
```
|
|
|
|
If successful, `nopy` will execute the `apt:essentials` cube against the container.
|
|
|
|
## 5. Manual Verification
|
|
|
|
You can connect to the container manually to verify changes:
|
|
|
|
**Via Docker Exec:**
|
|
|
|
```bash
|
|
docker exec -it nopy-test-container bash
|
|
```
|
|
|
|
**Via SSH (if configured):**
|
|
|
|
```bash
|
|
ssh -p 2222 testuser@localhost
|
|
# Password: password
|
|
```
|
|
|
|
## 6. Cleanup
|
|
|
|
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.
|