docs(configuration): add configuration docs (nitric.yaml)

Author: jyecusch

docs/basics/configuration.mdx

@@ -0,0 +1,236 @@
+---
+description: 'Configuring a Nitric Project using nitric.yaml'
+---
+
+# Configuration
+
+The Nitric CLI uses a configuration file named `nitric.yaml` to define the structure of your project. This file defines 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.
+
+<Note>
+  If you're new to Nitric and starting from a project template, you can skip
+  this section and start building your application. The `nitric.yaml` file will
+  be created for you. Use this section as a reference when you need to customize
+  your project configuration or understand how the configuration works.
+</Note>
+
+## Example `nitric.yaml`
+
+```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](/concepts/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:
+
+```yaml
+services:
+  - match: services/*
+    runtime: go
+    type: ''
+    start: go run ./$SERVICE_PATH/...
+```
+
+And the project structure below:
+
+```text
+services/
+  service1/
+    main.go
+  service2/
+    main.go
+```
+
+```text
+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.
+
+<Note>
+  If you're using a custom [runtime configuration](#runtimes), the `basedir`
+  value will be used as the context for the Docker build, i.e. it will override
+  the `context` value in the runtime configuration.
+</Note>
+
+#### `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](/concepts/stack).
+
+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.
+
+```yaml
+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:
+
+```yaml
+services:
+  - match: services/*
+    runtime: go
+    type: ''
+    start: go run ./$SERVICE_PATH/...
+```
+
+And the project structure below:
+
+```text
+services/
+  service1/
+    main.go
+  service2/
+    main.go
+```
+
+When running `nitric start`, the following commands will be executed:
+
+```bash
+go run ./services/service1/main.go
+go run ./services/service2/main.go
+```
+
+### `batch-services` (optional)
+
+A list of [batch service](/concepts/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 services](/concepts/service#batch) 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:
+
+```yaml
+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:
+
+```dockerfile
+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"]
+```
+
+<Note>
+  The Dockerfile only needs to start your application. The Nitric CLI will
+  automatically wrap this Dockerfile with additional build steps to inject the
+  Nitric runtime and build context for the target platform.
+</Note>
+
+#### `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.
+
+<Note>
+  Any services using this runtime which have a `basedir` value set will use the
+  `basedir` value as the build context instead of the `context` value.
+</Note>
+
+#### `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:
+
+```yaml
+runtimes:
+  go:
+    dockerfile: ./golang.dockerfile
+    context: ''
+    args:
+      GO_VERSION: 1.16
+```

docs/getting-started/deployment.mdx renamed to docs/basics/deployment.mdx

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.