---
title: "Dockerfile detection"
url: "https://docs.alisx.com/reference/dbd/dockerfile-detection/"
---
# Dockerfile detection

The rules `alis build` applies to find, name and build a service's Docker images.

## Detected files

| File under the service folder | Build context | Image |
|---|---|---|
| `Dockerfile` | the service folder | `neurons/<service-id>` |
| `<folder>/Dockerfile` | `<folder>/` | `neurons/<service-id>/<folder>` |
| `<name>.Dockerfile` | the service folder | `neurons/<service-id>/<name>` |
| `<folder>/<name>.Dockerfile` | `<folder>/` | `neurons/<service-id>/<folder>/<name>` |

Examples: `worker/Dockerfile` builds `neurons/orders-v1/worker`; `bff.Dockerfile` builds `neurons/orders-v1/bff`; `web/app.Dockerfile` builds `neurons/orders-v1/web/app` from `web/`.

## Name rules

| Rule | Detail |
|---|---|
| Characters | `<name>` starts with a lowercase letter, contains only lowercase letters, digits and single hyphens, and ends with a letter or digit. |
| Length | At most 30 characters. |
| Suffix | Only the exact `.Dockerfile` suffix counts. `bff.dockerfile` and `Dockerfile.bff` print a warning and are not built. |
| Conflicts | Two files that build one image, for example `bff.Dockerfile` and `bff/Dockerfile`, fail the build. |
| Renames | Moving `bff/Dockerfile` to `bff.Dockerfile` keeps the image name. |

## Context and ignore files

A named Dockerfile at the service root sees the whole service folder as its context. Add a `<name>.Dockerfile.dockerignore` beside it to exclude files, and `COPY` only what the image needs. For Go, one `go.mod` at the service root with a `cmd/<image>` main package per image shares packages between images.

## Image reference

```hcl
${var.ALIS_PRODUCT_REGION}-docker.pkg.dev/${var.ALIS_OS_PRODUCT_PROJECT}/neurons/${var.ALIS_OS_NEURON}[/<folder>][/<name>]:${var.ALIS_OS_NEURON_VERSION_COMMIT_SHA}
```

The tag is the build-repo commit the version was built from.

## Flags that select images

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--build-path` | string, repeatable | all detected | Image to build, relative to the service folder: a Dockerfile's folder (`.`, `worker`) or a named `<name>.Dockerfile`. |
| `--retag` | bool | false | Retag the latest previous images instead of building the detected Dockerfiles. Warns when an image's build context changed since the last build. |
| `--retag-path` | string, repeatable | none | Image to retag, relative to the service folder. |
| `--confirm-no-paths` | bool | false | Confirm that the service has no images to build or retag. |

## Image and version states

| State | Meaning |
|---|---|
| `BUILDING` | Busy building. |
| `BUILT` | Built and ready to deploy. |
| `RETAGGED` | The previous image was retagged under this version. |
| `FAILED` | The build failed; the version's `logs_url` is set. |

A version's state aggregates its images' states.