Configuration

The Nitric CLI uses a configuration file named nitric.yaml to define the structure of your project. This file specifies the name of your project, where nitric should look for the entrypoints to your application, and other project-specific settings.

Projects created from a template using the Nitric CLI will have a nitric.yaml file created for you. If you are creating a project from scratch, you can create a nitric.yaml file in the root of your project.

Example nitric.yaml

name: my-project
services:
  - match: services/*
    runtime: go
    type: ''
    start: go run ./$SERVICE_PATH/...
runtimes:
  go:
    dockerfile: ./golang.dockerfile
    context: ''
    args: {}

Configuration Options

name

The name of your project. This is used to identify your project and it used when auto-generating service and resource names during deployment.

services

A list of service types that make up your project. Typically, nitric will build each service in your project into a separate container image. Each service can have its own runtime, build configuration, and start command.

match

A glob pattern that matches service entrypoints. Each file matching this pattern will be treated as a separate service. This allows multiple services to share a single runtime configuration and type.

For example, with the following configuration:

services:
  - match: services/*
    runtime: go
    type: ''
    start: go run ./$SERVICE_PATH/...

And the project structure below:

services/
  service1/
    main.go
  service2/
    main.go

services/
├── service1/
│   └── main.go
└── service2/
    └── main.go

Both service1/main.go and service2/main.go will be treated as separate services with the same runtime configuration.

basedir (optional)

The base directory to search for service entrypoints. If not provided, the base directory is the root of the project. This is useful when you want to group services under a specific directory or you're working with a monorepo.

runtime (optional)

The runtime to use for this service. For certain languages like JavaScript, Python and Dart the runtime can be inferred from the file extension. For other languages, you will need to specify the runtime.

If a runtime is provided it must match the name of a runtime configuration in the runtimes section.

type (optional)

Type is essentially the name for this group of services. It is used to group services together for deployment and resource management. If not provided, the service will be grouped under the 'default' type.

The most common use case for this is grouping service with similar deployed resource requirements together. For example, you make have a set of services that required additional vCPU or memory resources at runtime. You can group these services together under a specific type and apply resource constraints to that type in a stack file.

For example, if you have a set of services that require additional memory, you can group them together under a type named memory-intensive, separate from the default type.

services:
  - match: services/other/*
    runtime: go
    start: go run ./$SERVICE_PATH/...
  - match: services/memory-intensive/*
    runtime: go
    # Group these services under the 'memory-intensive' type
    type: memory-intensive
    start: go run ./$SERVICE_PATH/...

start (optional)

The command to start the service during local development. This command is used when running locally using the nitric start CLI command. This command will be executed once for each service, with the $SERVICE_PATH environment variable set to the path to the service entrypoint.

For example, with the following configuration:

services:
  - match: services/*
    runtime: go
    type: ''
    start: go run ./$SERVICE_PATH/...

And the project structure below:

services/
  service1/
    main.go
  service2/
    main.go

When running nitric start, the following commands will be executed:

go run ./services/service1/main.go
go run ./services/service2/main.go

batch-services (optional)

A list of batch service types that make up your project. Batch services are used to run high-performance computing tasks, data processing or tasks requiring GPUs, or a large number of vCPUs or memory.

Batch services are similar to services but are optimized for running batch processing tasks. You can read more about batch services in the batch service section.

The configuration options for batch-services are the same as for services.

runtimes (optional)

A list of runtime configurations that can be used by services in your project. Each runtime configuration defines how to build a service for a specific runtime. For example, this can be used to define a custom Dockerfile for a specific runtime.

For example, with the following configuration:

runtimes:
  go:
    dockerfile: ./golang.dockerfile
    context: ''
    args: {}

Nitric ships with a set of default runtime configurations for common languages. You can override these default configurations by providing your own runtime configuration. The runtime configuration must match the runtime name used in the services section.

dockerfile

The path to the Dockerfile template used to build the services. This path is relative to the root of the project. The Dockerfile template will be provided with the following arguments:

• HANDLER: The service entrypoint path relative to the base directory.

Here is an example of a Dockerfile template for Go services:

FROM golang:alpine AS build

# Include the HANDLER argument, nitric will populate this with the service entrypoint path
ARG HANDLER

WORKDIR /app/

COPY go.mod *.sum ./

RUN go mod download

# Note: Operations like COPY are relative to the `basedir` value in service configuration.
# Or the root of the project if not provided.
COPY . .

# Build the Go App from the provided HANDLER (this will be based on matches in your nitric.yaml fle)
RUN go build -o /bin/main ./${HANDLER}/...

FROM alpine

COPY --from=build /bin/main /bin/main

RUN chmod +x-rw /bin/main
RUN apk update && \
  apk add --no-cache tzdata ca-certificates && \
  update-ca-certificates

ENTRYPOINT ["/bin/main"]

context (optional)

The build context to use when building the container image. This is the directory that will be provided to the Docker build command as the build context. If not provided, the build context will be the root of the project.

args (optional)

A map of additional arguments to provide to the Docker build command. These arguments will be provided to the Docker build command as --build-arg arguments.

For example, with the following configuration:

runtimes:
  go:
    dockerfile: ./golang.dockerfile
    context: ''
    args:
      GO_VERSION: 1.16