# Compose file

> The Compose keys East India accepts, and what each means for a Windows machine.

East India reads Docker's Compose file format. Each service becomes one or more Hyper-V machines. A key East India does not accept is refused with `UNSUPPORTED_FIELD`, naming its path, so a typing mistake never passes silently. `endia compose config` prints the file as East India reads it.

## Top level

`name`, `services`, `networks`, `volumes`, and keys starting `x-`, which are ignored as Docker ignores them. `version` is ignored with Docker's warning that it is obsolete. Any other key, including `configs`, `secrets`, `include` and `models`, is refused with `UNSUPPORTED_FIELD` naming its path.

## Service keys

Any key not in this table is refused with `UNSUPPORTED_FIELD` naming its path, for example `services.trainee.privileged`. A service with neither `image` nor `build` is refused with `INVALID_DEFINITION` and Docker's message.

| Key | Form | Meaning |
|---|---|---|
| `image` | string | The image the machines are made from. With `build`, the tag the built image receives. A service with `build` and no `image` gets the tag `<project>-<service>`, which means `:latest`, as Docker names it. |
| `build` | string (the context), or `{ context, dockerfile, args, labels }` | The image is built as `endia build` builds it. Without `dockerfile`, the recipe is `Endiafile` in the context when the context holds one, and `Dockerfile` otherwise. |
| `command` | string or list | Overrides the image's `CMD`. A string is split into words by Docker's shell-word rules, without a shell. |
| `entrypoint` | string or list | Overrides the image's `ENTRYPOINT` and clears its `CMD` unless `command` is given. |
| `environment` | map, or list of `KEY=VALUE` or `KEY` | Variables for the main process, health checks and exec. `KEY` alone takes the command line's value, and is left out when the command line has none. |
| `env_file` | string, list of strings, or list of `{ path, required }` | Variable files read by the command line, in Docker's format; `environment` overrides them. A missing file with `required` true (the default) is refused with `INVALID_DEFINITION`. |
| `working_dir` | string | Working folder of the main process, health checks and exec. |
| `user` | string | Account of the main process and health checks. |
| `hostname` | string | The machine's computer name. |
| `container_name` | string | The machine name. More than one replica is refused with `INVALID_DEFINITION`. |
| `labels` | map or list | Labels of the machines. |
| `networks` | list of names, or map of name to `{ aliases, ipv4_address }` or null | The fleet's networks the machines join. |
| `extra_hosts` | list of `host=address` or `host:address`, or map | Extra hosts file lines; the address `host-gateway` stands for the PC. |
| `ports` | list | Published ports. |
| `expose` | list | Recorded; opens nothing. |
| `volumes` | list | Named volumes and bind mounts. |
| `depends_on` | list or map | The services to start first, with `service_started`, `service_healthy` or `service_completed_successfully`. |
| `healthcheck` | map | The machine's health check. |
| `restart` | string | Whether the machine starts again when its main process exits. |
| `deploy.replicas` | integer, 0 or more | Number of machines. Default 1. |
| `scale` | integer | The older form of `deploy.replicas`. Both given with different values is refused with `INVALID_DEFINITION`. |
| `deploy.resources.limits.cpus`, `cpus` | number or string, more than 0 | Processors and processor limit. |
| `deploy.resources.limits.memory`, `mem_limit` | Docker byte string | The most memory the machine may grow to, rounded up to a multiple of 2 MiB. Less than 2 GiB is refused with `INVALID_DEFINITION`: Windows needs that much to run. |
| `stop_grace_period` | Docker duration | Time an orderly shutdown may take before the virtual machine is turned off. |
| `platform` | string | Only `windows/amd64`. |
| `develop.watch` | list | Read, and printed by `compose config`; nothing acts on it in this release. |
| `x-eastindia.screen` | string `<width>x<height>`, such as `1920x1080` | The size of the machines' screen. Width 640 to 3840, height 480 to 2160. Without it the screen is Hyper-V's 1024 by 768. A changed size makes `compose up` recreate the machines. |

Durations use Docker's form: a sequence of numbers with units `us`, `ms`, `s`, `m`, `h`, such as `1m30s`. Byte strings use Docker's form: a number with an optional unit `b`, `k`, `kb`, `m`, `mb`, `g`, `gb` (powers of 1024).

## Memory, processors and ports

**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. `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. 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.

## Names and networks

- **Names.** Machines on the same network reach each other by service name. 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 network card on the PC's `Default Switch`, through which it reaches the internet and the PC, unless all its networks are marked `internal: true`.
- **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 ...`.
