Package ids and folders¶
How a package id names a service, where its folders live on disk, and how the CLI resolves the organisation, product and service from the working directory.
Package id format¶
| Part | Meaning | Example |
|---|---|---|
<org> |
The build environment (organisation) id | acme |
<product> |
The product id | sh |
<path> |
The service path, one or more dot-separated segments | orders, internal.api |
<vN> |
The service version, v plus a number |
v1, v2 |
Mapping¶
| Package id | Resource name | Build folder | Define folder |
|---|---|---|---|
acme.sh.orders.v1 |
organisations/acme/products/sh/neurons/orders-v1 |
~/alis.build/acme/build/sh/orders/v1 |
~/alis.build/acme/define/acme/sh/orders/v1 |
acme.sh.internal.api.v2 |
organisations/acme/products/sh/neurons/internal-api-v2 |
~/alis.build/acme/build/sh/internal/api/v2 |
~/alis.build/acme/define/acme/sh/internal/api/v2 |
- The service id is the path with
/replaced by-, followed by the version. - The protobuf
packagestatement equals the package id:package acme.sh.orders.v1;. - The generated Go package for a
v1service is imported asalis.build/<org>/<product>/<path>, for examplealis.build/acme/sh/orders. - The build folder holds the implementation, its Dockerfiles and
infra/. The define folder holds the.protofiles.
Repositories on disk¶
| Repository | Path | Contents |
|---|---|---|
| Definitions repo (one per build environment) | ~/alis.build/<org>/define |
<org>/<product>/<path>/<vN>/*.proto for every service of every product |
| Build repo (one per product) | ~/alis.build/<org>/build/<product> |
<path>/<vN>/ per service, and .alis/.env for local runs |
alis clone <org>.<product> creates both; a repository already on disk is fast-forward pulled.
Context resolution¶
alis context view --json prints what the CLI resolves from the working directory: organisation, product, packageId, serviceFolder, defineFolder and the product's environments[] with id, displayName, status, production and projectId. Sections that cannot be resolved are omitted with the reason under notes.
| Working directory | What can be omitted |
|---|---|
Inside ~/alis.build/<org>/build/<product>/<path>/<vN> |
The package id: alis build, alis define, alis deploy, alis packages install act on that service. |
Inside ~/alis.build/<org>/build/<product> |
The <org>.<product> reference: alis product view, alis environment list. Dot-references fill right-aligned, so alis environment refresh <env-id> expands to <org>.<product>.<env-id>. |
Outside ~/alis.build |
Nothing; pass the full reference. |
--cwd <dir> runs a command as if from that directory without changing the shell.
Commits and branches¶
| Command | Commit used |
|---|---|
alis define |
The latest pushed commit of the definitions repo; --commit <sha> pins one. |
alis build |
The latest pushed commit touching the service folder on the checked-out branch; --branch <branch> chooses another pushed branch; --commit <sha> pins one. A detached checkout must pass --branch. |
Unpushed work is never built or defined.
Inside a workstation¶
A workstation's CLI resolves only its own build environment. ALIS_BUILD_SHELL=1, ALIS_ORGANISATION=<org> and ALIS_WORKSTATION=organisations/<org>/workstations/<id> are set; a command on another build environment exits 1 with "this workstation is locked to build environment ...". alis workstation url <port> prints the address of a port on the machine from ALIS_PORT_URL_TEMPLATE.