Skip to content

Create a service

Register a new service in a product and get its working folders in both repositories. A service (called a neuron in resource names) is one deployable unit of a product: one contract, one or more images, one Terraform module.

Prerequisites

  • Builder access to the product.
  • The product's repositories cloned with alis clone <org>.<product>.
  • A package id for the service: <org>.<product>.<path>.<vN>, for example acme.sh.orders.v1. The path may have several segments, such as acme.sh.internal.api.v2.

Steps

  1. Register the service.

    alis service new acme.sh.orders.v1 --json

    The result names the service and the folders it created:

    JSON
    {
  "packageId": "acme.sh.orders.v1",
  "name": "organisations/acme/products/sh/neurons/orders-v1",
  "serviceId": "orders-v1",
  "created": true,
  "buildFolder": "/Users/you/alis.build/acme/build/sh/orders/v1",
  "defineFolder": "/Users/you/alis.build/acme/define/acme/sh/orders/v1",
  "next": ["..."]
}

    Folders are created only in the repositories already on disk: orders/v1 plus orders/v1/infra in the build repo, and acme/sh/orders/v1 in the definitions repo. No files are generated.

  2. Write the contract in the define folder and publish it. See Define your API.

  3. Write the implementation, a Dockerfile and infra/ in the build folder. See Write a Dockerfile for your service and Write infrastructure with Terraform.
  4. Commit and push, then build and deploy. See Build a version.
  1. Open the product and go to Services.
  2. Choose Add neuron and enter the identifier without its version, for example orders; the console adds the version and shows the neuron it will create, orders-v1.
  3. Run alis clone acme.sh on your machine, then create the folders yourself: orders/v1 and orders/v1/infra in the build repo, and acme/sh/orders/v1 in the definitions repo.

Naming

Part Rule Example
Build environment id 3 to 21 lowercase letters or digits, starting with a letter acme
Product id two lowercase characters sh
Service path one or more lowercase segments orders, internal.api
Version v followed by a number v1, v2
Service id the path with / replaced by -, plus the version orders-v1, internal-api-v2