Deploying machines

Deploying a single machine

A Compose file with one service describes one machine:

compose.yaml
name: orders-dev
services:
  dev:
    image: lab/app:dev
    ports:
      - "18080:8080"
Terminal
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 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:

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.

depends_on also accepts service_started and service_completed_successfully. The Compose file reference 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:

Terminal
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

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.

Terminal
$ 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:

Terminal
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:

    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.