diff --git a/content/docs/tutorial/working-with-a-custom-module-registry/en.md b/content/docs/tutorial/working-with-a-custom-module-registry/en.md index 2332d2664..489facdb0 100644 --- a/content/docs/tutorial/working-with-a-custom-module-registry/en.md +++ b/content/docs/tutorial/working-with-a-custom-module-registry/en.md @@ -9,6 +9,13 @@ tags: toc_hide: true --- +{{{with _script "en" "cue mod registry"}}} +# TODO: this is inherently racey. But not a problem in practice... +# for now. When it does become a problem we can solve this properly +# using a nc-based wait loop or similar. +nohup cue mod registry localhost:5000 > /tmp/cue_mod_registry 2>&1 & +{{{end}}} + ## Introduction In this tutorial you will learn how to create and work with CUE modules, @@ -54,8 +61,6 @@ We would like to be able to share the schema between several consumers. Create a directory to hold the schema code: {{{with script "en" "create-frostyconfig"}}} -#norun - mkdir frostyconfig cd frostyconfig {{{end}}} @@ -68,8 +73,6 @@ you will create as they are needed. Initialize the directory as a module: {{{with script "en" "initialize-frostyconfig-module"}}} -#norun - cue mod init glacial-tech.example/frostyconfig@v0 {{{end}}} @@ -164,8 +167,6 @@ tutorial. Set up some required envirionment variables: {{{with script "en" "init-environ"}}} -#norun - export CUE_EXPERIMENT=modules export CUE_REGISTRY=localhost:5000/cuemodules {{{end}}} @@ -176,7 +177,7 @@ support is currently in its experimental phase. The `CUE_REGISTRY` variable tells the `cue` command which registry to use when fetching and pushing modules. In our example the modules will be stored in the registry under the prefix `cuemodules`. -In practice you would want this prefix to be some place of your choice - +In practice you would want this prefix to be some place of your choice - or you could leave the prefix empty if you plan to dedicate the registry to holding CUE modules. {{{end}}} @@ -185,8 +186,6 @@ to holding CUE modules. Ensure the `module.cue` file is tidy: {{{with script "en" "frostyconfig-v0.0.1-tidy"}}} -#norun - cue mod tidy {{{end}}} This command checks that modules for all imported packages @@ -200,8 +199,6 @@ have any dependencies, we will run `cue mod tidy` anyway. Publish the first version of this module: {{{with script "en" "frostyconfig-v0.0.1-publish"}}} -#norun - cue mod publish v0.0.1 {{{end}}} @@ -232,8 +229,6 @@ published. Create a directory for the new module and initalize it: {{{with script "en" "init-frostyapp"}}} -#norun - mkdir ../frostyapp cd ../frostyapp cue mod init glacial-tech.example/frostyapp@v0 @@ -266,23 +261,14 @@ constrained by the `frostyconfig.#Config` schema. Ensure the module is tidy, pulling all dependencies: {{{with script "en" "frostyapp-tidy-1"}}} -#norun - cue mod tidy {{{end}}} We can see that the dependencies have now been added to the `cue.mod/module.cue` file: - -{{{with upload "en" "frostyapp-tidy-result-1"}}} --- frostyapp/cue.mod/module.cue -- -module: "glacial-tech.example/frostyapp@v0" -deps: { - "glacial-tech.example/frostyconfig@v0": { - v: "v0.0.1" - } -} +{{{with script "en" "show frostyapp-tidy-result-1"}}} +cat cue.mod/module.cue {{{end}}} Our dependencies currently look like this: @@ -298,22 +284,11 @@ flowchart TD Export the configuration as YAML: {{{with script "en" "frostyapp-export-1"}}} -#norun - cue export --out yaml {{{end}}} We can use this new module code just like any other CUE code. - -Here is the output: -``` -config: - appName: alpha - port: 80 - features: - logging: true -``` {{{end}}} ## Publish a `frostytemplate` module @@ -329,8 +304,6 @@ other source of truth. Create a directory for the new module and initalize it: {{{with script "en" "init-frostytemplate"}}} -#norun - mkdir ../frostytemplate cd ../frostytemplate cue mod init glacial-tech.example/frostytemplate@v0 @@ -370,8 +343,6 @@ We import the schema to constrain the default values, just as we did with the Publish the `frostytemplate` module: {{{with script "en" "frostytemplate-v0.0.1-publish"}}} -#norun - cue mod tidy cue mod publish v0.0.1 {{{end}}} @@ -383,6 +354,11 @@ cue mod publish v0.0.1 Update the `frostyapp` module to make use of this new template module: + +{{{with script "en" "back to frostyapp to use template"}}} +cd ../frostyapp +{{{end}}} + {{{with upload "en" "update-frostyapp"}}} -- frostyapp/config.cue -- package frostyapp @@ -403,8 +379,6 @@ requirements of the configuration. Resolve dependencies in `frostyapp`: {{{with script "en" "frostyapp-tidy-2"}}} -#norun - cue mod tidy {{{end}}} @@ -413,18 +387,8 @@ use `frostytemplate` as well as `frostyconfig`. Here is what the `cue.mod/module.cue` file now looks like: - -{{{with upload "en" "frostyapp-tidy-result-2"}}} --- frostyapp/cue.mod/module.cue -- -module: "glacial-tech.example/frostyapp@v0" -deps: { - "glacial-tech.example/frostyconfig@v0": { - v: "v0.0.1" - } - "glacial-tech.example/frostytemplate@v0": { - v: "v0.0.1" - } -} +{{{with script "en" "show frostyapp-tidy-result-2"}}} +cat cue.mod/module.cue {{{end}}} {{< mermaid caption="Current dependencies" >}} @@ -438,23 +402,11 @@ flowchart TD Re-render the configuration as YAML: {{{with script "en" "rerender-config"}}} -#norun - cue export --out yaml {{{end}}} -We can see that the values in the configuration reflect the new default values: +We can see that the values in the configuration reflect the new default values. - -``` -config: - appName: alpha - port: 80 - debug: false - features: - logging: true - analytics: true -``` {{{end}}} ## Add a new field to the schema @@ -466,6 +418,10 @@ We will add that field to the schema and update the app to use it. {{{with step}}} Update the schema to add a new `maxConcurrency` field: +{{{with script "en" "return to schema to add maxConcurrency field"}}} +cd ../frostyconfig +{{{end}}} + {{{with upload "en" "schema-v0.1.0"}}} -- frostyconfig/config.cue -- package frostyconfig @@ -498,9 +454,6 @@ The schema is unchanged except for the new `maxConcurrency` field. Upload a new version of the `frostyconfig` schema: {{{with script "en" "upload-schema2"}}} -#norun - -cd ../frostyconfig cue mod tidy cue mod publish v0.1.0 {{{end}}} @@ -514,6 +467,11 @@ compatible feature has been added. {{{with step}}} Edit the `cue.mod/module.cue` file to use the new version: + +{{{with script "en" "return to app to use updated schema"}}} +cd ../frostyapp +{{{end}}} + {{{with upload "en" "edit-dependency-version"}}} -- frostyapp/cue.mod/module.cue -- module: "glacial-tech.example/frostyapp@v0" @@ -549,13 +507,11 @@ future the `cue` command will be able to perform this kind of update. Check that everything still works and that your configuration is still valid: {{{with script "en" "check-update-ok"}}} -#norun - cue mod tidy cue export --out yaml {{{end}}} -So exactly has happened above? +So exactly what happened above? Recall that the `glacial-tech.example/frostytemplate` module remains unchanged: its module still depends on the original `v0.0.1` version of the schema. By diff --git a/content/docs/tutorial/working-with-a-custom-module-registry/gen_cache.cue b/content/docs/tutorial/working-with-a-custom-module-registry/gen_cache.cue index 5d826253d..693388383 100644 --- a/content/docs/tutorial/working-with-a-custom-module-registry/gen_cache.cue +++ b/content/docs/tutorial/working-with-a-custom-module-registry/gen_cache.cue @@ -9,15 +9,221 @@ package site upload: { "schema-v0.0.1": "CRGo79n3o4NmUhzy5+M3af6mvIU5q6FOS+P5wGqgwjg=" "config.cue": "zKPD1hDfvw6/nM6q2kQ182z4658t//2orqtrhD4z2Rc=" - "frostyapp-tidy-result-1": "SThDwT1oSytv5ajAIOUJAS0qTkLuTvl93gj/kEg6Tp8=" "second-module-to-publish": "wGrtKO60Va0hh6x6evOT6YZ6xYC3MvXf51Gu7xv7aEk=" "update-frostyapp": "ivq7HnDXXcTNv/214RNsLbtXO+p9AbInhuDt5OaP1+c=" - "frostyapp-tidy-result-2": "Drld15H+R6HC2KHWKOXANypFKxk0JXZGsMBO9aqpkVw=" "schema-v0.1.0": "UYTajks9MuZgEetGLpab2bKsvMwl2Dz4aliBtTyBPig=" "edit-dependency-version": "20qyCFMqHE2OqhL8ILndmu3pTkvbwoZaZgEuUzHRo0g=" } multi_step: { - "L7S29D7H9KBSTB4I0K201FJNR5BB6BL0C79CF15FIFRS1MBBSJ80====": [] + "RF9RTOT7E9BUKIOV1MSPV8OJ12NNE464ANK1JVV93T24V3PSTRQ0====": [{ + doc: """ + # TODO: this is inherently racey. But not a problem in practice... + # for now. When it does become a problem we can solve this properly + # using a nc-based wait loop or similar. + """ + cmd: "nohup cue mod registry localhost:5000 >/tmp/cue_mod_registry 2>&1 &" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "mkdir frostyconfig" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cd frostyconfig" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod init glacial-tech.example/frostyconfig@v0" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "export CUE_EXPERIMENT=modules" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "export CUE_REGISTRY=localhost:5000/cuemodules" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod publish v0.0.1" + exitCode: 0 + output: """ + published glacial-tech.example/frostyconfig@v0.0.1 + + """ + }, { + doc: "" + cmd: "mkdir ../frostyapp" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cd ../frostyapp" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod init glacial-tech.example/frostyapp@v0" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cat cue.mod/module.cue" + exitCode: 0 + output: """ + module: "glacial-tech.example/frostyapp@v0" + language: { + \tversion: "v0.8.0-0.dev" + } + deps: { + \t"glacial-tech.example/frostyconfig@v0": { + \t\tv: "v0.0.1" + \t} + } + + """ + }, { + doc: "" + cmd: "cue export --out yaml" + exitCode: 0 + output: """ + config: + appName: alpha + port: 80 + features: + logging: true + + """ + }, { + doc: "" + cmd: "mkdir ../frostytemplate" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cd ../frostytemplate" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod init glacial-tech.example/frostytemplate@v0" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod publish v0.0.1" + exitCode: 0 + output: """ + published glacial-tech.example/frostytemplate@v0.0.1 + + """ + }, { + doc: "" + cmd: "cd ../frostyapp" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cat cue.mod/module.cue" + exitCode: 0 + output: """ + module: "glacial-tech.example/frostyapp@v0" + language: { + \tversion: "v0.8.0-0.dev" + } + deps: { + \t"glacial-tech.example/frostyconfig@v0": { + \t\tv: "v0.0.1" + \t} + \t"glacial-tech.example/frostytemplate@v0": { + \t\tv: "v0.0.1" + \t} + } + + """ + }, { + doc: "" + cmd: "cue export --out yaml" + exitCode: 0 + output: """ + config: + appName: alpha + port: 80 + debug: false + features: + logging: true + analytics: true + + """ + }, { + doc: "" + cmd: "cd ../frostyconfig" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod publish v0.1.0" + exitCode: 0 + output: """ + published glacial-tech.example/frostyconfig@v0.1.0 + + """ + }, { + doc: "" + cmd: "cd ../frostyapp" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue mod tidy" + exitCode: 0 + output: "" + }, { + doc: "" + cmd: "cue export --out yaml" + exitCode: 0 + output: """ + config: + appName: alpha + port: 80 + debug: false + features: + logging: true + analytics: true + + """ + }] } } } diff --git a/hugo/content/en/docs/tutorial/working-with-a-custom-module-registry/index.md b/hugo/content/en/docs/tutorial/working-with-a-custom-module-registry/index.md index ebfa60fed..c585a4cb1 100644 --- a/hugo/content/en/docs/tutorial/working-with-a-custom-module-registry/index.md +++ b/hugo/content/en/docs/tutorial/working-with-a-custom-module-registry/index.md @@ -167,7 +167,7 @@ support is currently in its experimental phase. The `CUE_REGISTRY` variable tells the `cue` command which registry to use when fetching and pushing modules. In our example the modules will be stored in the registry under the prefix `cuemodules`. -In practice you would want this prefix to be some place of your choice - +In practice you would want this prefix to be some place of your choice - or you could leave the prefix empty if you plan to dedicate the registry to holding CUE modules. {{< /step >}} @@ -190,6 +190,7 @@ have any dependencies, we will run `cue mod tidy` anyway. Publish the first version of this module: ```text { title="TERMINAL" codeToCopy="Y3VlIG1vZCBwdWJsaXNoIHYwLjAuMQo=" } $ cue mod publish v0.0.1 +published glacial-tech.example/frostyconfig@v0.0.1 ``` This command uploads the module to the registry and publishes it @@ -256,9 +257,12 @@ $ cue mod tidy We can see that the dependencies have now been added to the `cue.mod/module.cue` file: - -```cue { title="frostyapp/cue.mod/module.cue" } +```text { title="TERMINAL" codeToCopy="Y2F0IGN1ZS5tb2QvbW9kdWxlLmN1ZQo=" } +$ cat cue.mod/module.cue module: "glacial-tech.example/frostyapp@v0" +language: { + version: "v0.8.0-0.dev" +} deps: { "glacial-tech.example/frostyconfig@v0": { v: "v0.0.1" @@ -280,19 +284,15 @@ flowchart TD Export the configuration as YAML: ```text { title="TERMINAL" codeToCopy="Y3VlIGV4cG9ydCAtLW91dCB5YW1sCg==" } $ cue export --out yaml -``` - -We can use this new module code just like any other CUE code. - - -Here is the output: -``` config: appName: alpha port: 80 features: logging: true ``` + +We can use this new module code just like any other CUE code. + {{< /step >}} ## Publish a `frostytemplate` module @@ -348,6 +348,7 @@ Publish the `frostytemplate` module: ```text { title="TERMINAL" codeToCopy="Y3VlIG1vZCB0aWR5CmN1ZSBtb2QgcHVibGlzaCB2MC4wLjEK" } $ cue mod tidy $ cue mod publish v0.0.1 +published glacial-tech.example/frostytemplate@v0.0.1 ``` {{< /step >}} @@ -357,6 +358,11 @@ $ cue mod publish v0.0.1 Update the `frostyapp` module to make use of this new template module: + +```text { title="TERMINAL" codeToCopy="Y2QgLi4vZnJvc3R5YXBwCg==" } +$ cd ../frostyapp +``` + ```cue { title="frostyapp/config.cue" } package frostyapp @@ -384,9 +390,12 @@ use `frostytemplate` as well as `frostyconfig`. Here is what the `cue.mod/module.cue` file now looks like: - -```cue { title="frostyapp/cue.mod/module.cue" } +```text { title="TERMINAL" codeToCopy="Y2F0IGN1ZS5tb2QvbW9kdWxlLmN1ZQo=" } +$ cat cue.mod/module.cue module: "glacial-tech.example/frostyapp@v0" +language: { + version: "v0.8.0-0.dev" +} deps: { "glacial-tech.example/frostyconfig@v0": { v: "v0.0.1" @@ -409,12 +418,6 @@ flowchart TD Re-render the configuration as YAML: ```text { title="TERMINAL" codeToCopy="Y3VlIGV4cG9ydCAtLW91dCB5YW1sCg==" } $ cue export --out yaml -``` - -We can see that the values in the configuration reflect the new default values: - - -``` config: appName: alpha port: 80 @@ -423,6 +426,9 @@ config: logging: true analytics: true ``` + +We can see that the values in the configuration reflect the new default values. + {{< /step >}} ## Add a new field to the schema @@ -434,6 +440,10 @@ We will add that field to the schema and update the app to use it. {{< step stepNumber="18" >}} Update the schema to add a new `maxConcurrency` field: +```text { title="TERMINAL" codeToCopy="Y2QgLi4vZnJvc3R5Y29uZmlnCg==" } +$ cd ../frostyconfig +``` + ```cue { title="frostyconfig/config.cue" } package frostyconfig @@ -464,10 +474,10 @@ The schema is unchanged except for the new `maxConcurrency` field. {{< step stepNumber="19" >}} Upload a new version of the `frostyconfig` schema: -```text { title="TERMINAL" codeToCopy="Y2QgLi4vZnJvc3R5Y29uZmlnCmN1ZSBtb2QgdGlkeQpjdWUgbW9kIHB1Ymxpc2ggdjAuMS4wCg==" } -$ cd ../frostyconfig +```text { title="TERMINAL" codeToCopy="Y3VlIG1vZCB0aWR5CmN1ZSBtb2QgcHVibGlzaCB2MC4xLjAK" } $ cue mod tidy $ cue mod publish v0.1.0 +published glacial-tech.example/frostyconfig@v0.1.0 ``` We incremented the minor version to signify that a backwardly @@ -479,6 +489,11 @@ compatible feature has been added. {{< step stepNumber="20" >}} Edit the `cue.mod/module.cue` file to use the new version: + +```text { title="TERMINAL" codeToCopy="Y2QgLi4vZnJvc3R5YXBwCg==" } +$ cd ../frostyapp +``` + ```cue { title="frostyapp/cue.mod/module.cue" } module: "glacial-tech.example/frostyapp@v0" deps: { @@ -515,9 +530,16 @@ Check that everything still works and that your configuration is still valid: ```text { title="TERMINAL" codeToCopy="Y3VlIG1vZCB0aWR5CmN1ZSBleHBvcnQgLS1vdXQgeWFtbAo=" } $ cue mod tidy $ cue export --out yaml +config: + appName: alpha + port: 80 + debug: false + features: + logging: true + analytics: true ``` -So exactly has happened above? +So exactly what happened above? Recall that the `glacial-tech.example/frostytemplate` module remains unchanged: its module still depends on the original `v0.0.1` version of the schema. By