The .cro.yml File
.cro.yml file is stored in the root directory of a service. It provides some metadata about the service that is used in combination with the
cro development tool (both the CLI and the web version). It is intended that, if used, the file is committed to version control.
.cro.yml file is only used by the
cro development tool. It is not required for the correct operation of the service, and need not be included when the service is deployed (the
.dockerignore generated when stubbing the service excludes it from the container).
.cro.yml file should be a dictionary at the top level. It must include:
crowith a value of
1. This will allow for versioning of the file as Cro evolves.
id, followed by an ID for the service. The value may contain the letters A..Z and a..z, the digits 0..9, the underscore (
_), the dash (
-) and the forward slash ('/'). This will be used to identify the service when using the CLI (such as in
cro run service-id).
entrypoint, which is the Raku source file that should be run to start the service. It should be specified relative to the
.cro.ymlfile. This will be used by the
crodevelopment tool to start the service.
It may optionally include:
name, which provides a human-friendly name for the service. This will be displayed in the web UI. If not provided, the
idwill be used in its place.
cro: 1 id: flashcard-backend name: Flashcards Backend entrypoint: service.raku
An endpoint is something exposed by a service for services or applications to connect to. Most often, it's a network port. The stub services produced by Cro do not hard-code a port number, but instead take it from an environment variable.
Endpoints are specified as a list under the
endpoints key. For example, a service that accepts both HTTP and HTTPS would look as follows:
endpoints: - id: http name: HTTP (Insecure) protocol: http host-env: FLASHCARD_BACKEND_HTTP_HOST port-env: FLASHCARD_BACKEND_HTTP_PORT - id: https name: HTTP (Secure) protocol: https host-env: FLASHCARD_BACKEND_HTTPS_HOST port-env: FLASHCARD_BACKEND_HTTPS_PORT
id is used to identify the endpoint in commands and when referencing it from other services. The
name is for display in the user interface; it is optional and will default to the
protocol describes the protocol that the endpoint speaks; this is used when stubbing code to call the service from another service. Protocols include:
https- HTTP/1.1 and/or HTTP/2.0 secure (negotiated using ALPN)
http- HTTP/1.1 insecure
http2- HTTP/2.0 insecure (starts HTTP/2 by prior knowledge)
wss- web socket secure
ws- web socket insecure
REP(generated client would be a
PUB(generated client would be a
It is allowed to write multiple protocols with a comma. This is mostly useful when an endpoint handles both HTTP and web sockets (securely as
https,wss or insecurely as
port-env fields name environment variables that will be populated with the host and port that the endpoint should be hosted on.
links section describes which other Cro services this one references. It is used for
cro run and
cro trace (or running/tracing the services in the web interface) to inject environment variables indicating the host and port of the other endpoints. The environment variables can then instead be supplied by configuration management, Kubernetes, and so forth when deploying the service.
links section might look like:
links: - service: flashcard-backend endpoint: https host-env: FLASHCARD_BACKEND_HTTPS_HOST port-env: FLASHCARD_BACKEND_HTTPS_PORT - service: users endpoint: https host-env: USERS_HTTPS_HOST port-env: USERS_HTTPS_PORT
service is the ID of the service (defined by
id in its
endpoint is the ID of the endpoint (from the target service's
endpoints section), and
env is the environment variable specifying the host and port in the form
Services will usually need other resources, such as database connections, addresses of non-Cro services, and (development fake) security credentials. It may be convenient to inject these using the environment. The
env section provides a way to set environment variables that will be passed to the service. This is a handy way to store development configuration and cut down a little of the setup work needed when other developers want to get the services running.
env: - name: FLASH_DATABASE value: test-database.internal:6555 - name: JWT_SECRET value: my-dev-not-so-secret
Controlling automatic restarts§
cro run and
cro web will automatically restart the service when a file changes in any directory beneath where the
.cro.yml is located. All hidden files and directories are ignored by default (those starting with a
., for example
To add extra directories to ignore, create an
ignore section with a list of patterns in the
.cro.yml file. These are processed like
.gitignore. For example:
ignore: - node_modules/