Service — executable component

📍 Where to find this in the UI

• ServiceDefinitions: Infra → Architecture tab → Services
• ServiceInstances: Infra → Environments → {env} → Services

What is it? A service is a piece of code that runs continuously (backend, frontend, worker, API…).

In Wakastart, a service is defined at 2 levels.

ServiceDefinition (Architecture level)

This is the generic definition of the service. You describe:

→ The ServiceDefinition is the schema, not the thing that actually runs.

Configuring the build: rootDirectory, dockerfilePath, buildContext

Three ServiceDefinition parameters drive the docker build step:

The docker build that gets executed is equivalent to:

bashCopy
cd <repo>/<rootDirectory>
docker build -f <dockerfilePath> <buildContext>

Case 1 — Simple repo, Dockerfile at the root

textCopy
le BFF WakaStart/
├── Dockerfile
├── package.json
└── src/

Equivalent to: docker build -f Dockerfile . run at the repo root.

Case 2 — Monorepo, project in a subfolder

textCopy
le BFF WakaStart/
├── apps/
│   ├── backend/
│   │   ├── Dockerfile
│   │   ├── package.json
│   │   └── src/
│   └── worker/
└── packages/

You want to build only apps/backend and restrict Docker's access to files in that folder:

Equivalent to: cd apps/backend && docker build -f Dockerfile ..

The build only sees apps/backend/ — neither apps/worker/ nor packages/.

Case 3 — Monorepo with a shared lockfile (pnpm/yarn workspaces, turbo…)

Your service is in apps/backend/ but needs the root pnpm-lock.yaml and the shared packages/* packages to install:

textCopy
le BFF WakaStart/
├── pnpm-lock.yaml         ← lockfile racine
├── pnpm-workspace.yaml
├── apps/
│   └── backend/
│       └── Dockerfile     ← Dockerfile dédié, mais a besoin du contexte racine
└── packages/
    └── shared/

Equivalent to: docker build -f apps/backend/Dockerfile . at the repo root.

The Dockerfile can now do COPY pnpm-lock.yaml ./ and COPY packages/shared ./packages/shared since it has access to the whole repo.

Practical rules

• The smaller the buildContext, the faster the build (Docker sends fewer files to the daemon). If your service is self-contained in a subfolder, go with Case 2.
• If your Dockerfile needs files located above its own folder (root lockfile, sibling packages), go with Case 3 — a larger buildContext but a targeted dockerfilePath.
• A .dockerignore at the root of the buildContext excludes unwanted files (node_modules, .git, .next/cache…) from the context sent to the daemon.

ServiceInstance (Environment level)

This is the actual instance of a service in a given environment (e.g. backend in dev, backend in prod). It inherits default values from the Definition but can override them:

textCopy
ServiceDefinition "backend"          ServiceInstance backend (env prod)
├── role: BACK                       ├── definitionId → lien
├── defaultReplicas: 1               ├── replicas: 5             ← override prod
├── defaultPort: 3000                ├── port: null               ← utilise 3000
└── defaultMemoryLimit: 512Mi        └── memoryLimit: 2Gi          ← override prod

This is where the ServiceInstance:

• decides which Docker image is deployed (and therefore which build is used)
• binds variables to their actual values
• shows the deployments, logs, and metrics