Write a Dockerfile for your service¶

Place Dockerfiles so that Build finds them, names the images predictably and lets your Terraform reference them. Build detects images from the files in the service folder; nothing is configured elsewhere.

Prerequisites¶

A service folder in the product's build repo, for example ~/alis.build/acme/build/sh/orders/v1.
Docker knowledge: multi-stage builds and .dockerignore.

Place the Dockerfile¶

Build looks under the service folder for these files:

File	Build context	Image
`Dockerfile`	the service folder	`neurons/<service-id>`
`worker/Dockerfile`	`worker/`	`neurons/<service-id>/worker`
`bff.Dockerfile`	the service folder	`neurons/<service-id>/bff`
`web/app.Dockerfile`	`web/`	`neurons/<service-id>/web/app`

A subfolder with its own Dockerfile builds a separate image from that subfolder. A named <name>.Dockerfile builds an image whose context is the folder the file sits in, so several images can share code.

Name additional images¶

<name> starts with a lowercase letter, uses only lowercase letters, digits and single hyphens, ends with a letter or digit and is at most 30 characters long. Only the exact .Dockerfile suffix counts: bff.dockerfile and Dockerfile.bff print a warning and are not built. Two files that would build the same image, such as bff.Dockerfile and bff/Dockerfile, fail the build. Moving bff/Dockerfile to bff.Dockerfile keeps the image name.

Keep root-level images small¶

A named Dockerfile at the service root sees the whole service folder. COPY only what the image needs and add a <name>.Dockerfile.dockerignore beside it. For Go, keep one go.mod at the service root with a cmd/<image> main package per image so the images share packages.

Reach the private Go registry¶

A Go build that imports generated Alis packages (alis.build/...) must authenticate against your product's Go registry inside the container. Replace <region> with the product's default region and <product-project-id> with the projectId from alis product view acme.sh --json.

Dockerfile

FROM golang:1.26 AS builder
WORKDIR /app

ENV GOPROXY=proxy.golang.org
RUN go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 add-locations --locations=<region>

COPY . ./

RUN go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@v0.4.0 refresh
ENV GOPROXY=https://<region>-go.pkg.dev/<product-project-id>/define-go,https://proxy.golang.org,direct
ENV GONOSUMDB=alis.build

RUN CGO_ENABLED=0 GOOS=linux go build -mod=readonly -o /server .

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder /server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

Do not copy credentials into the image; the auth helper obtains a short-lived token during the build.

Reference the image from Terraform¶

HCL

image = "${var.ALIS_PRODUCT_REGION}-docker.pkg.dev/${var.ALIS_OS_PRODUCT_PROJECT}/neurons/${var.ALIS_OS_NEURON}:${var.ALIS_OS_NEURON_VERSION_COMMIT_SHA}"

For a named image append its name: .../neurons/${var.ALIS_OS_NEURON}/bff:${var.ALIS_OS_NEURON_VERSION_COMMIT_SHA}.

Build one image, or none¶

alis build --build-path worker builds only that image (a Dockerfile's folder such as . or worker, or a named <name>.Dockerfile; repeatable).
alis build --retag retags the previous images instead of building; --retag-path limits that to some images.
A service with no Dockerfile at all, such as one that only owns infrastructure, builds with alis build --confirm-no-paths.