Deploying machines
Deploying a single machine
A Compose file with one service describes one machine:
name: orders-dev
services:
dev:
image: lab/app:dev
ports:
- "18080:8080"
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:
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 range10.231.0.0/16, cut into/24subnets, one subnet per network. Every machine also has a card on the PC'sDefault Switch, which reaches the internet and the PC, unless all its networks are markedinternal: 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 exampleendia compose exec --index 2 client ....
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:
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.
cpfollows 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 withexec, for exampleendia exec <machine> cmd /c "mkdir C:\app".cpworks in both directions:endia cp orders-dev-dev-1:C:/results ./resultsfetches files. - Running.
execwaits 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 asSYSTEM, outside the desktop session.-u,-wand-eset the account, the working folder and the environment.exec -dreturns 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 asC:\My Folder\; - every other backslash, and every argument without those characters, passes unchanged.
- an argument that is empty or contains a space, tab, line break or
- PowerShell. A PowerShell command run with
-Commandexits with the code of its last statement, so add-ErrorAction Stopto a command that must fail theexecwhen it fails, for exampleendia 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 (-tchanges the wait). - Bind mounts. Each time
endia compose upcreates, 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.
$ 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:
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:
-
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 as127.0.0.1:27017:27017cannot be reached from a machine. -
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.
-
Give the PC a name in the machine with
extra_hostsand the addresshost-gateway, as in Docker:compose.yamlservices: 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 markedinternal: truehas no card on the Default Switch, so it cannot usehost-gateway.