# Deploying machines

> Deploy one machine or a fleet from a Compose file, change software in a running machine, see what runs in it and reach services on the PC.

## Deploying a single machine

A Compose file with one service describes one machine:

```yaml title="compose.yaml"
name: orders-dev
services:
  dev:
    image: lab/app:dev
    ports:
      - "18080:8080"
```

```sh
endia compose up --wait
```

The machine is named `<project>-<service>-<n>`, here `orders-dev-dev-1`. `up --wait` returns once the machine is running and ready. Ready means that its virtual machine runs, its configuration was applied in this boot, and nothing has failed since. When the image has a desktop account, that account must also be signed in, with the desktop helper running. A machine with a health check must also be healthy.

A service with no `entrypoint` or `command`, in the Compose file or in its image, has no main process, and its machine keeps running until you stop it. That suits a machine you work in for hours. A service with a main process behaves like a container: when the program exits, the machine shuts down, and `restart:` decides whether it starts again.

| To | Run |
|---|---|
| see the machine and its state | `endia compose ps` or `endia ps` |
| stop it, keeping its disk | `endia compose stop` |
| start it again | `endia compose start` |
| restart Windows in it | `endia restart orders-dev-dev-1` |
| remove it and its disk | `endia compose down` |

**Memory and processors.** A machine starts with 2 GiB of memory, or with its `mem_limit` when that is smaller. Windows gives memory back while it is idle, down to 512 MiB, and receives more when it needs it, up to `mem_limit`, or up to 4 GiB when the service sets none. A `mem_limit` below 2 GiB is refused, because Windows needs at least that much. `cpus` sets the number of processors, rounded up; a fraction also caps their use. The default is 2.

**Published ports.** A published port listens on the PC's `127.0.0.1` only, and East India joins each connection to `127.0.0.1:<target>` inside the machine. In the example, a program on the PC reaches the machine's port 8080 at `127.0.0.1:18080`. From a sandbox, connect to `host.docker.internal:18080` after allowing `localhost:18080` in the sandbox's policy, as [Connecting an agent's sandbox](/docs/get-started/sandbox/) does for port 7443. A port given without a published number gets a free one between 49152 and 65535, which can change when the machine restarts; `endia inspect <machine>` lists each port's `published` number.

## Deploying many machines

The same Compose file format describes a fleet of machines that work together:

```yaml title="compose.yaml"
name: orders-test
services:
  server:
    image: lab/app:dev
    command: ["C:\\app\\OrderService.exe"]
    healthcheck:
      test: ["CMD", "curl.exe", "-fs", "http://127.0.0.1:8080/health"]
      interval: 5s
    networks: [lab]
  client:
    image: lab/app:dev
    deploy:
      replicas: 3
    depends_on:
      server:
        condition: service_healthy
    networks: [lab]
networks:
  lab: {}
```

`endia compose up --wait` creates one server and three clients: `orders-test-server-1` and `orders-test-client-1` to `-3`. It starts the server first and waits until its health check passes, because the clients depend on it being healthy. `--scale client=5` changes the number of clients for one run.

- **Names.** Machines on the same network reach each other by service name: each client reaches the server at `server`. East India writes the names into every machine's hosts file, because it runs no DNS server.
- **Networks.** Each network in the file is a private Hyper-V switch with its own address range, taken from the configured `defaultAddressPools`. By default these are the range `10.231.0.0/16`, cut into `/24` subnets, one subnet per network. Every machine also has a card on the PC's `Default Switch`, which reaches the internet and the PC, unless all its networks are marked `internal: true`.
- **Boots.** At most two machines boot at the same time; the others wait their turn. A fleet of six takes about three boot times to come up.
- **Volumes.** A named volume is a separate disk that keeps its data until `endia compose down -v`. It belongs to one machine.
- **Replicas.** Commands that act on one replica take `--index`, for example `endia compose exec --index 2 client ...`.

`depends_on` also accepts `service_started` and `service_completed_successfully`. The [Compose file reference](/docs/reference/compose/) lists every key East India accepts; any other key is refused with `UNSUPPORTED_FIELD`, naming it, so a typing mistake never passes silently. `endia compose config` shows the file as East India reads it.

### Relaunching a running fleet

Running `endia compose up` again on a running fleet updates it to match the file. By default it recreates only a machine whose service or image changed, keeps every other machine as it is, and leaves alone a machine whose service is no longer in the file, as Docker Compose does. Recreating a machine removes it with its disk and creates it again from its image. These options change that, and matter mostly when the fleet is already up:

| To | Run | When it matters |
|---|---|---|
| launch only some services | `endia compose up web db` | when you want part of a fleet, or are working on one service; the services they depend on come up too |
| replace every machine | `endia compose up --force-recreate` | when you want fresh machines from their images, even though nothing in the file changed |
| keep existing machines, even changed ones | `endia compose up --no-recreate` | when a machine holds work you have not saved elsewhere and a changed service would otherwise replace it |
| remove machines of services no longer in the file | `endia compose up --remove-orphans` | after you rename or delete a service, so that its old machines do not keep running |

The desktop app's Launch a fleet always uses the defaults: every service, machines recreated only when changed, and no machine removed for a service the file no longer has. Use the CLI or the API (`services`, `recreate` and `removeOrphans` of the request) to choose otherwise.

## Changing software in a running machine

`endia cp` copies files into a running machine, and `endia exec` runs programs in it. Together they install, update and remove software without rebuilding an image:

```sh
endia cp ./publish/. orders-dev-dev-1:C:/app            # copy the folder's contents into C:\app
endia exec orders-dev-dev-1 msiexec /i C:\app\Orders.msi /quiet
endia exec orders-dev-dev-1 msiexec /x C:\app\Orders.msi /quiet
endia exec orders-dev-dev-1 cmd /c rmdir /s /q C:\app
```

- **Copying.** `cp` follows Docker's rules for where a copy lands. A source path ending in `/.` copies a folder's contents; without it, the folder itself is copied into the destination folder. Copying replaces files of the same name and leaves other files in place. The destination folder must already exist, as in Docker, so create it first with `exec`, for example `endia exec <machine> cmd /c "mkdir C:\app"`. `cp` works in both directions: `endia cp orders-dev-dev-1:C:/results ./results` fetches files.
- **Running.** `exec` waits for the program and exits with its exit code: the full code on Windows, that code modulo 256 on Linux. 127 means the program was not found, and 126 that it could not start. Programs run as `SYSTEM`, outside the desktop session. `-u`, `-w` and `-e` set the account, the working folder and the environment. `exec -d` returns at once and prints the program's real Windows process ID; `endia process wait <machine> <pid>` then waits until the program ends and prints its exit code.
- **Arguments.** Windows receives the program and its arguments as one command line. East India builds that line by the rules of `CommandLineToArgvW`, which Windows programs use to split their command line:
  - an argument that is empty or contains a space, tab, line break or `"` goes in double quotes;
  - inside the quotes, a `"` becomes `\"`;
  - backslashes before a `"`, or at the end of the argument, are doubled: `C:\My Folder\` arrives as `"C:\My Folder\\"`, and the program reads it back as `C:\My Folder\`;
  - every other backslash, and every argument without those characters, passes unchanged.
- **PowerShell.** A PowerShell command run with `-Command` exits with the code of its last statement, so add `-ErrorAction Stop` to a command that must fail the `exec` when it fails, for example `endia exec <machine> powershell -NoProfile -Command "Get-Content C:\app\version.txt -ErrorAction Stop"`.
- **Stopping a program.** `endia process stop <machine> <pid>` asks the program to close and ends it after 10 seconds (`-t` changes the wait).
- **Bind mounts.** Each time `endia compose up` creates, starts or keeps a machine, East India copies the folder of a Compose bind mount, such as `./fixtures:C:/fixtures`, into it. The copy deletes files that the source no longer has. Changes made inside the machine never come back.

## Inspecting a machine

**Processes.** `endia process ls <machine>` lists every process, as `docker top` does: its process ID, parent, session, account, start time and program name. Session 0 holds services; the desktop user's session holds what runs on the screen.

**Windows.** `endia desktop windows <machine>` lists every visible window on the desktop, frontmost first: the process ID and program name that own it, its handle, its position and size in pixels from the top-left corner of the screen, and its title. `--format json` gives the same list as JSON, one window per line. `endia process inspect <machine> <pid>` shows one process in full, including its hidden windows.

```console
$ endia desktop windows orders-dev-dev-1
PID    NAME       HANDLE     POSITION   SIZE       TITLE
4120   Orders     0x2a0b4c   100,50     800x600    Orders
```

**Inside a window.** `endia desktop inspect <machine> <pid>` prints the window's user-interface tree, as Windows UI Automation sees it, in JSON: each button, text box and menu with its control type, name, automation ID and position within the window.

**Services.** East India has no command of its own for Windows services; use Windows' tools through `exec`:

```sh
endia exec orders-dev-dev-1 sc query state= all
endia exec orders-dev-dev-1 powershell -NoProfile -Command "Get-Service | Where-Object Status -eq Running"
```

## Reaching services on the PC

A machine can reach services that run on the PC. Each machine whose networks are not all internal has a card on the PC's `Default Switch`, which Windows in the machine names `internet`. The PC's address on the `Default Switch` is the machine's default gateway. A service on the PC answers a machine there when it listens on all of the PC's addresses and the Windows firewall lets the connection in.

For example, to keep a database in Docker on the PC and use it from a machine:

1. Publish the database's port on all the PC's addresses, which is Docker's default: `docker run -d -p 27017:27017 mongo`. A port published as `127.0.0.1:27017:27017` cannot be reached from a machine.
2. Allow the port through the PC's Windows firewall, for example with an inbound rule for TCP 27017 limited to the Default Switch's address range.
3. Give the PC a name in the machine with `extra_hosts` and the address `host-gateway`, as in Docker:

   ```yaml title="compose.yaml"
   services:
     app:
       image: lab/app:dev
       extra_hosts:
         - "pc=host-gateway"
   ```

   The application then connects to `mongodb://pc:27017`. East India writes the PC's current Default Switch address into the machine's hosts file each time the machine starts, because Windows chooses that address and can change it when the PC restarts. A service whose networks are all marked `internal: true` has no card on the Default Switch, so it cannot use `host-gateway`.
