Orbit’s API ships as a container image. The pipeline should build that image once per commit, tag it so you always know what code is inside, push it to a registry and hand the exact tag to the deploy jobs. This lesson builds that, and explains the trade-offs between the ways to run docker build inside CI.
The Dockerfile
At the root of the Orbit repository:
FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY dist/ ./dist/
USER node
EXPOSE 8080
CMD ["node", "dist/server.js"]
Two stages keep build tools out of the final image, USER node avoids running as root and copying package-lock.json before the source lets Docker reuse the dependency layer when only code changed. The Docker Tutorial covers these ideas in detail.
The GitLab container registry
Every GitLab project has a container registry, enabled by default on GitLab.com. GitLab gives every job what it needs to use it:
| Variable | Value |
|---|---|
CI_REGISTRY | Registry host, registry.gitlab.com on GitLab.com |
CI_REGISTRY_IMAGE | Base image path for the project, e.g. registry.gitlab.com/orbit-team/orbit |
CI_REGISTRY_USER | A username valid for this job |
CI_REGISTRY_PASSWORD | A job-scoped password, valid only while the job runs |
No personal tokens, no stored passwords. You will find pushed images under Deploy → Container registry.
Docker-in-Docker
The job’s container needs a Docker daemon to talk to. The usual answer on hosted runners is Docker-in-Docker (dind): a second container running dockerd, attached to the job as a service.
build-image:
stage: package
image: docker:29
services:
- docker:29-dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
needs: [build-api]
before_script:
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
What each part does:
image: docker:29provides the Docker CLI.services: docker:29-dindstarts a Docker daemon next to the job, reachable at the hostnamedocker.DOCKER_TLS_CERTDIR: "/certs"makes the daemon and CLI share generated TLS certificates, so the connection is encrypted. Keep the CLI and daemon on the same major version.needs: [build-api]downloads thedist/artifact that the Dockerfile copies.--password-stdinkeeps the password out of the process list and the log.
dind needs a privileged container. GitLab’s hosted Linux runners allow it. On your own runners it means privileged = true in config.toml, which gives job containers broad power over the host. Use dedicated runners for image builds, or the daemonless options below.
Tagging strategy
A tag answers the question “what is inside this image?”. Use tags that never move for deployments and moving tags only for convenience:
| Tag | Example | Moves? | Use it for |
|---|---|---|---|
| Commit SHA | orbit:3f9c2a1b | Never | Deploys, rollbacks, tracing a bug to a commit |
| Version | orbit:1.4.0 | Never | Releases from Git tags |
| Branch slug | orbit:feature-dark-mode | Every push | Review apps |
latest / main | orbit:main | Every merge | Local testing only |
build-image:
# ...same as above...
script:
- docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
- docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
- |
if [ -n "$CI_COMMIT_TAG" ]; then
docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
fi
Never deploy latest. A re-deploy of an old pipeline (lesson 7) must get the old image, and only a fixed tag guarantees that.
Add useful labels
Labels make an image explain itself. The OCI standard keys are understood by registries and scanners:
$ docker build \
--label "org.opencontainers.image.revision=$CI_COMMIT_SHA" \
--label "org.opencontainers.image.source=$CI_PROJECT_URL" \
--label "org.opencontainers.image.created=$CI_PIPELINE_CREATED_AT" \
-t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
Faster builds with a registry cache
Every dind job starts with an empty daemon, so Docker’s layer cache is gone and every build starts from zero. BuildKit can store its cache in the registry and pull it back next time:
build-image:
stage: package
image: docker:29
services:
- docker:29-dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
CACHE_REF: $CI_REGISTRY_IMAGE/cache:buildcache
needs: [build-api]
before_script:
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker buildx create --use --driver docker-container
script:
- >
docker buildx build
--cache-from type=registry,ref=$CACHE_REF
--cache-to type=registry,ref=$CACHE_REF,mode=max
--tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
--push .
mode=max caches the layers of every stage, including the deps stage, so an unchanged package-lock.json skips npm ci entirely. On a typical Node.js service this turns a three-minute build into thirty seconds.
Multi-architecture images
Graviton and other ARM machines are cheaper than x86 for many workloads. Buildx builds both in one go and pushes a single tag that works on either:
$ docker buildx build --platform linux/amd64,linux/arm64 \
--tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" --push .
Cross-building uses emulation and is slow for compiled languages. For heavy builds, run one job per architecture on native runners (for example saas-linux-small-arm64) and join the results with docker buildx imagetools create.
Building without a Docker daemon
You may not want privileged containers at all. Options that build images without dockerd:
| Tool | How it works | Notes |
|---|---|---|
| BuildKit rootless | moby/buildkit:rootless image runs buildctl-daemonless.sh | Same engine as docker buildx, no privileged mode on most runners |
| Buildah | Builds OCI images from a Dockerfile without a daemon | Common on Red Hat based platforms |
| Kaniko | Was the classic answer | Google archived the project in 2025; community forks exist, but prefer an actively maintained tool for new pipelines |
A rootless BuildKit job looks like this:
build-image-rootless:
stage: package
image:
name: moby/buildkit:rootless
entrypoint: [""]
variables:
BUILDKITD_FLAGS: --oci-worker-no-process-sandbox
needs: [build-api]
before_script:
- mkdir -p ~/.docker
- |
AUTH=$(printf "%s:%s" "$CI_REGISTRY_USER" "$CI_REGISTRY_PASSWORD" | base64 | tr -d '\n')
echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$AUTH\"}}}" > ~/.docker/config.json
script:
- >
buildctl-daemonless.sh build
--frontend dockerfile.v0
--local context=.
--local dockerfile=.
--output type=image,name=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA,push=true
Services for integration tests
The services keyword is not only for dind. Any image can run next to a job, which is perfect for testing against real dependencies:
integration-tests:
stage: test
image: node:24-alpine
services:
- name: postgres:17-alpine
alias: db
- name: redis:8-alpine
alias: cache
variables:
POSTGRES_DB: orbit_test
POSTGRES_USER: orbit
POSTGRES_PASSWORD: orbit-test-only
DATABASE_URL: postgres://orbit:orbit-test-only@db:5432/orbit_test
REDIS_URL: redis://cache:6379
script:
- npm ci
- npm run test:integration
The services are reachable under their alias. They are thrown away after the job, so tests always start from a clean database. Lesson 9 builds on this.
Keep the registry tidy
A busy project pushes hundreds of images a week. Turn on a cleanup policy under Settings → Packages and registries → Container registry: for example, keep the 20 most recent tags matching .*, always keep tags matching v\d+\.\d+\.\d+, and delete everything else older than 30 days. Production rollbacks need the release tags, not every commit from last year.
Exercise
Why should the deploy job use $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA rather than :latest?
Show answer
Answer: C. latest moves with every push, so the same deploy job could ship different code at different times. An immutable tag ties each deployment to one commit, which makes rollbacks and debugging reliable.
Exercise
Your dind builds take three minutes because npm ci runs from scratch every time. What helps most?
Show answer
Answer: B. Each dind job starts with an empty daemon, so local layers are lost. A registry cache lets BuildKit pull previous layers, so unchanged steps like npm ci are skipped.
Key takeaways
- Every project has a container registry; CI jobs log in with job-scoped credentials.
- Docker-in-Docker is simple but needs privileged containers; keep CLI and daemon versions matched and TLS on.
- Deploy immutable tags (commit SHA, version), never
latest. - BuildKit’s registry cache restores layers across jobs; buildx builds multi-arch images.
- Rootless BuildKit or Buildah avoid privileged runners; Kaniko is archived.
servicesrun databases and caches next to a job for integration tests.
FAQ
I get “Cannot connect to the Docker daemon at tcp://docker:2375”. Why?
The dind service is missing, the runner is not privileged, or the TLS settings do not match. With DOCKER_TLS_CERTDIR: "/certs" the client talks to port 2376 with TLS; make sure you did not also set DOCKER_HOST to port 2375.
Can I mount the runner’s Docker socket instead of using dind?
Yes, on your own runners, and it is fast because it shares the host’s layer cache. But every job then controls the host’s Docker, which equals root on that machine. Only do it on runners dedicated to one trusted project.
Should I push images to Docker Hub or a cloud registry instead?
Use whatever your runtime pulls from fastest and most securely. Many teams build into GitLab’s registry and copy release images to Amazon ECR or another cloud registry in the deploy stage. Lesson 11 pushes to ECR.
How do I scan the image for vulnerabilities?
Add GitLab’s container scanning after the build job. Lesson 10 covers it together with SAST, secret detection and dependency scanning.
Why does my image build pass locally but fail in CI?
Usually missing files: .dockerignore excludes something, or the dist/ artifact was not downloaded because the job does not need the build job. List the build context with ls -la in the job to check.