Skip to main content

Examples

This section provides some examples on how to run the CLI to setup a project from the Amido Stacks projects.

Note

It is assumed that the Stacks CLI command has been installed and is in the path to be called using the stacks name.

The following table shows the settings that are being used in each of the examples.

Example settings
NameValueDescription

company

MyCompany

Name of the company that the project is being created for

area

core

The area within the company that the project is relevant to.

In previous versions of the CLI, this has been referred to as the domain, but it has been changed to area to avoid confusion with DNS domain.

component

backend

Component that the project is for

domain

stacks-example.com

DNS domain for which the application will respond to

cloud

azure

The cloud platform being used

region

ukwest

Region in the cloud that the resources will be deployed to

group

mywebapi-resources

Group that holds all of the cloud resources

tfgroup

supporting-group

Group that has the resources to be used to hold the Terraform state

tfstorage

kjh56sdfnjnkjn

Name of the storage that will hold the Terraform state

tfcontainer

tfstate

Container in the storage for the state files

name

my-webapi

Name of the project to create in the working directory

framework_option

webapi

The option within the framework being created.

For dotnet or java the options are webapi, cqrs or events. For infra the options are aks.

.NET

The following table shows the additional options that are required when scaffolding the .NET examples.

NameValueDescription
frameworkdotnetFramework being used, e.g. dotnet, java or infra
framework_versionv6.0.274Version of the framework option to grab.

.NET Specific settings

.NET WebApi project from command line

Run the following command to create the new project in the working directory, which will be the directory that the command is being run in.

BashPowerShell
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

This will get the specified version of the framework project, create a new project based on the options specified and then update the build files to work with those settings. Finally it will initalise a new git repository in the new project directory. All of the commands that have been run by the CLI will be saved in the cmdlog.txt file in the directory that the command was run in.

CLI with command line options

Figure 1 shows the output of the command running in PowerShell. It also shows the commands that have been run in the cmdlog.txt.

The resultant project, as stated by the Project path: statement in the screenshot, contains all the necessary files to run a simple .NET WebApi. The following listing shows that the solutions have been renamed with the company name as the namespace, as shown on lines 19, 26, 29 and 36.

└───my-webapi
β”œβ”€β”€β”€.github
β”œβ”€β”€β”€build
β”‚ └───azDevOps
β”‚ └───azure
β”‚ └───templates
β”‚ └───steps
β”‚ └───build
β”œβ”€β”€β”€contracts
β”œβ”€β”€β”€deploy
β”‚ β”œβ”€β”€β”€azure
β”‚ β”‚ └───app
β”‚ β”‚ └───kube
β”‚ β”œβ”€β”€β”€k8s
β”‚ β”‚ └───app
β”‚ └───scripts
└───src
β”œβ”€β”€β”€api
β”‚ β”œβ”€β”€β”€MyCompany.core.API
β”‚ β”‚ β”œβ”€β”€β”€Authentication
β”‚ β”‚ β”œβ”€β”€β”€Authorization
β”‚ β”‚ └───Controllers
β”‚ β”‚ β”œβ”€β”€β”€Category
β”‚ β”‚ β”œβ”€β”€β”€DOMAIN
β”‚ β”‚ └───Item
β”‚ β”œβ”€β”€β”€MyCompany.core.API.Models
β”‚ β”‚ β”œβ”€β”€β”€Requests
β”‚ β”‚ └───Responses
β”‚ └───MyCompany.core.API.UnitTests
β”‚ └───Controllers
β”‚ β”œβ”€β”€β”€Category
β”‚ β”œβ”€β”€β”€DOMAIN
β”‚ └───Item
└───tests
└───Functional
└───MyCompany.core.API.FunctionalTests
β”œβ”€β”€β”€Builders
β”‚ └───Http
β”œβ”€β”€β”€Configuration
β”œβ”€β”€β”€Models
└───Tests
β”œβ”€β”€β”€Fixtures
β”œβ”€β”€β”€Steps
└───Stories

.NET WebApi project using the interactive command

The interactive command is designed to ask questions on the command line about the configuration required for setting up Amido Stacks. It will then save this configuration out to a file that can be read in using the scaffold command.

stacks-cli interactive

The values as specified in the previous configuration table have been used in the following screenshot of the interactive session.

stackscli interactive

The resulting configuration file contains all of the configuration that was used to generate the projects, which means it can be used to produce the same project stack again.

log:
level: info
format: text
colour: true
directory:
working: "C:\\Users\\RussellSeymour\\scratch\\projects"
business:
company: My Company
domain: core
component: backend
cloud:
platform: azure
network:
base:
domain:
external: example-stacks.com
pipeline: azdo
project:
- name: my-webapi
framework:
type: dotnet
option: webapi
version: v3.0.232
platform:
type: aks
sourcecontrol:
type: github
url: https://github.com/russellseymour/my-webapi
cloud:
region: ukwest
group: mywebapi-resources
stacks:
dotnet:
webapi:
url: https://github.com/amido/stacks-dotnet
trunk: master
cqrs:
url: https://github.com/amido/stacks-dotnet-cqrs
trunk: master
events:
url: https://github.com/amido/stacks-dotnet-cqrs-events
trunk: master
java:
webapi:
url: https://github.com/amido/stacks-java
trunk: master
cqrs:
url: https://github.com/amido/stacks-java-cqrs
trunk: main
events:
url: https://github.com/amido/stacks-java-cqrs-events
trunk: main
nodejs:
csr:
url: https://github.com/amido/stacks-typescript-csr
trunk: master
ssr:
url: https://github.com/amido/stacks-typescript-ssr
trunk: master
infra:
aks:
url: https://github.com/amido/stacks-infrastructure-aks
trunk: master
terraform:
backend:
storage: kjh56sdfnjnkjn
group: supporting-group
container: tfstate
options:
cmdlog: false
dryrun: false
nobanner: false
nocliversion: false

The command that needs to be run next is displayed at the end of the output.

.NET WebApi project using a configuration file

The CLI can be used with a configuration file to generate the Amido Stacks based projects.

Note

The configuration file that is used in the following example is from the previous example. However, any valid configuration file can be used.

stacks-cli scaffold -c ./stacks.yml

The CLI will use the configuration file to scaffold the requested projects.

Scaffolding projects with a configuration file

As has been seen with using the scaffolding command with command line options, the resultant project has been created with the namespace set to the specified company name.

└───my-webapi
β”œβ”€β”€β”€.github
β”œβ”€β”€β”€build
β”‚ └───azDevOps
β”‚ └───azure
β”‚ └───templates
β”‚ └───steps
β”‚ └───build
β”œβ”€β”€β”€contracts
β”œβ”€β”€β”€deploy
β”‚ β”œβ”€β”€β”€azure
β”‚ β”‚ └───app
β”‚ β”‚ └───kube
β”‚ β”œβ”€β”€β”€k8s
β”‚ β”‚ └───app
β”‚ └───scripts
└───src
β”œβ”€β”€β”€api
β”‚ β”œβ”€β”€β”€MyCompany.core.API
β”‚ β”‚ β”œβ”€β”€β”€Authentication
β”‚ β”‚ β”œβ”€β”€β”€Authorization
β”‚ β”‚ └───Controllers
β”‚ β”‚ β”œβ”€β”€β”€Category
β”‚ β”‚ β”œβ”€β”€β”€DOMAIN
β”‚ β”‚ └───Item
β”‚ β”œβ”€β”€β”€MyCompany.core.API.Models
β”‚ β”‚ β”œβ”€β”€β”€Requests
β”‚ β”‚ └───Responses
β”‚ └───MyCompany.core.API.UnitTests
β”‚ └───Controllers
β”‚ β”œβ”€β”€β”€Category
β”‚ β”œβ”€β”€β”€DOMAIN
β”‚ └───Item
└───tests
└───Functional
└───MyCompany.core.API.FunctionalTests
β”œβ”€β”€β”€Builders
β”‚ └───Http
β”œβ”€β”€β”€Configuration
β”œβ”€β”€β”€Models
└───Tests
β”œβ”€β”€β”€Fixtures
β”œβ”€β”€β”€Steps
└───Stories

Java

The following table shows the additional options that are required when scaffolding the Java examples.

NameValueDescription
frameworkjavaFramework being used, e.g. dotnet, java or infra
framework_versionv1.0.0Version of the framework option to grab.

Java Specific settings

Java WebApi project from command line

Run the following command to scaffold a new Java project based on the Amido WebApi Java project. The project will be created in the working directory, which in this case will be the directory that the command has is being run under.

BashPowerShell
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]
[object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object][object Object]

This command will download version v1.0.0, from the GitHub releases for the project, into a temporary directory. It will then run the specified Maven commands from the project settings file and scaffold a new project with the specified name, in the current directory. Once the project has been setup it will be initialised as Git repository and, where applicable, set the remote origin for the repo. All of the commands that are executed by the CLI will be saved in a file called cmdlog.txt.

CLI scaffolding Java project from command line

As the option to save all the commands that are executed by the CLI has been specified, the cmdlog.txt file for the above command is as follows.

Command log for the Java webapi scaffold

The resultant project, as stated by the Project path: statement in the screenshot, contains all the necessary files to run a simple Java WebApi. The following listing shows that the solutions have been renamed with the company name as the namespace.

└───my-webapi
β”œβ”€β”€β”€api-tests
β”‚ β”œβ”€β”€β”€.mvn
β”‚ β”‚ └───wrapper
β”‚ └───src
β”‚ └───test
β”‚ β”œβ”€β”€β”€java
β”‚ β”‚ └───com
β”‚ β”‚ └───MyCompany
β”‚ β”‚ └───core
β”‚ β”‚ └───backend
β”‚ β”‚ └───tests
β”‚ β”‚ β”œβ”€β”€β”€menu
β”‚ β”‚ β”œβ”€β”€β”€models
β”‚ β”‚ β”œβ”€β”€β”€pact
β”‚ β”‚ β”‚ └───pacts
β”‚ β”‚ β”œβ”€β”€β”€status
β”‚ β”‚ β”œβ”€β”€β”€stepdefinitions
β”‚ β”‚ └───templates
β”‚ └───resources
β”‚ β”œβ”€β”€β”€cucumber
β”‚ β”‚ └───features
β”‚ β”‚ └───status
β”‚ └───templates
β”œβ”€β”€β”€api-tests-karate
β”‚ β”œβ”€β”€β”€.mvn
β”‚ β”‚ └───wrapper
β”‚ └───src
β”‚ └───test
β”‚ β”œβ”€β”€β”€java
β”‚ β”‚ └───org
β”‚ β”‚ └───MyCompany
β”‚ β”‚ └───core
β”‚ β”‚ └───backend
β”‚ β”‚ └───tests
β”‚ └───resources
β”œβ”€β”€β”€build
β”‚ β”œβ”€β”€β”€azDevOps
β”‚ β”‚ └───azure
β”‚ β”‚ β”œβ”€β”€β”€coverage
β”‚ β”‚ └───templates
β”‚ β”‚ └───steps
β”‚ β”‚ β”œβ”€β”€β”€build
β”‚ β”‚ └───deploy
β”‚ └───jenkins
β”‚ └───azure
β”œβ”€β”€β”€deploy
β”‚ β”œβ”€β”€β”€azure
β”‚ β”‚ └───app
β”‚ β”‚ └───kube
β”‚ └───k8s
β”‚ └───app
└───java
β”œβ”€β”€β”€.mvn
β”‚ └───wrapper
β”œβ”€β”€β”€src
β”‚ β”œβ”€β”€β”€main
β”‚ β”‚ β”œβ”€β”€β”€java
β”‚ β”‚ β”‚ └───com
β”‚ β”‚ β”‚ └───MyCompany
β”‚ β”‚ β”‚ └───core
β”‚ β”‚ β”‚ └───backend
β”‚ β”‚ β”‚ └───menu
β”‚ β”‚ β”‚ β”œβ”€β”€β”€api
β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€β”€v1
β”‚ β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€β”€dto
β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€β”€request
β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ └───response
β”‚ β”‚ β”‚ β”‚ β”‚ └───impl
β”‚ β”‚ β”‚ β”‚ └───v2
β”‚ β”‚ β”‚ β”‚ └───impl
β”‚ β”‚ β”‚ β”œβ”€β”€β”€domain
β”‚ β”‚ β”‚ └───mappers
β”‚ β”‚ └───resources
β”‚ β”‚ └───local
β”‚ └───test
β”‚ └───java
β”‚ └───com
β”‚ └───MyCompany
β”‚ └───core
β”‚ └───backend
β”‚ β”œβ”€β”€β”€actuator
β”‚ β”œβ”€β”€β”€menu
β”‚ β”‚ β”œβ”€β”€β”€api
β”‚ β”‚ β”‚ β”œβ”€β”€β”€v1
β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€β”€dto
β”‚ β”‚ β”‚ β”‚ β”‚ └───response
β”‚ β”‚ β”‚ β”‚ └───impl
β”‚ β”‚ β”‚ └───v2
β”‚ β”‚ β”‚ └───impl
β”‚ β”‚ β”œβ”€β”€β”€domain
β”‚ β”‚ └───mappers
β”‚ └───util
└───target
└───classes
└───local

Java WebApi project using the interactive command

As with the .NET example, it is possible to create a configuration file interactively to scaffold out a new project Java project. This is achieved using the interactive sub-command.

Note

The examples shown here have been run in WSL on Windows 11.

---
stacks-cli interactive
---

The values specified in the example are the ones as show in the configuration table and are the same as the settings used in the Java example fo scaffolding from the command line.

stackscli interactive java

The resulting configuration file contains all of the configuration that was used to generate the projects, which means it can be used to produce the same project stack again.

log:
level: info
format: text
colour: true
file: ""
directory:
working: /home/russells/projects
business:
company: My Company
domain: core
component: backend
cloud:
platform: azure
network:
base:
domain:
external: example-stacks.com
pipeline: azdo
project:
- name: my-webapi
framework:
type: java
option: webapi
version: v1.0.0
sourcecontrol:
type: github
url: https://github.com/my-company/my-webapi
cloud:
region: ukwest
group: mywebapi-resources
stacks:
dotnet:
webapi:
url: https://github.com/amido/stacks-dotnet
trunk: master
cqrs:
url: https://github.com/amido/stacks-dotnet-cqrs
trunk: master
events:
url: https://github.com/amido/stacks-dotnet-cqrs-events
trunk: master
java:
webapi:
url: https://github.com/amido/stacks-java
trunk: master
cqrs:
url: https://github.com/amido/stacks-java-cqrs
trunk: main
events:
url: https://github.com/amido/stacks-java-cqrs-events
trunk: main
nodejs:
csr:
url: https://github.com/amido/stacks-typescript-csr
trunk: master
ssr:
url: https://github.com/amido/stacks-typescript-ssr
trunk: master
infra:
aks:
url: https://github.com/amido/stacks-infrastructure-aks/
trunk: master
terraform:
backend:
storage: kjh56sdfnjnkjn
group: supporting-group
container: tfstate
options:
cmdlog: true
dryrun: false
nobanner: false
nocliversion: false

The command that needs to be run next is displayed at the end of the output.

Java WebApi project using a configuration file

The Amido Stacks CLI can be used with a configuration file to setup multiple projects in one go.

Note

The configuration file used in this example is the one that was generated from the interactive command in the previous example.

Note

The examples shown here have been run in WSL on Windows 11.

stacks-cli scaffold -c ./stacks.yml

The CLI will use the configuration file to get all the settings required to scaffold the projects that have been requested.

Scaffold Java project

As the configuration file was configured with a company name with a space in it, the CLI has modified the value so it will be compatible with the commands that need to be run. This can be seen in the output of the CLi in the above image.

└── my-webapi
β”œβ”€β”€ api-tests
β”‚Β Β  └── src
β”‚Β Β  └── test
β”‚Β Β  β”œβ”€β”€ java
β”‚Β Β  β”‚Β Β  └── com
β”‚Β Β  β”‚Β Β  └── My_Company
β”‚Β Β  β”‚Β Β  └── core
β”‚Β Β  β”‚Β Β  └── backend
β”‚Β Β  β”‚Β Β  └── tests
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ menu
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ models
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ pact
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── pacts
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ status
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ stepdefinitions
β”‚Β Β  β”‚Β Β  └── templates
β”‚Β Β  └── resources
β”‚Β Β  β”œβ”€β”€ cucumber
β”‚Β Β  β”‚Β Β  └── features
β”‚Β Β  β”‚Β Β  └── status
β”‚Β Β  └── templates
β”œβ”€β”€ api-tests-karate
β”‚Β Β  └── src
β”‚Β Β  └── test
β”‚Β Β  β”œβ”€β”€ java
β”‚Β Β  β”‚Β Β  └── components
β”‚Β Β  β”‚Β Β  └── menu
β”‚Β Β  └── resources
β”œβ”€β”€ build
β”‚Β Β  β”œβ”€β”€ azDevOps
β”‚Β Β  β”‚Β Β  └── azure
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ coverage
β”‚Β Β  β”‚Β Β  └── templates
β”‚Β Β  β”‚Β Β  └── steps
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ build
β”‚Β Β  β”‚Β Β  └── deploy
β”‚Β Β  └── jenkins
β”‚Β Β  └── azure
β”œβ”€β”€ deploy
β”‚Β Β  β”œβ”€β”€ azure
β”‚Β Β  β”‚Β Β  └── app
β”‚Β Β  β”‚Β Β  └── kube
β”‚Β Β  └── k8s
β”‚Β Β  └── app
└── java
β”œβ”€β”€ src
β”‚Β Β  β”œβ”€β”€ main
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ java
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── com
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── My_Company
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── core
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── backend
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── menu
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ api
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ v1
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ dto
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ request
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── response
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── impl
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── v2
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── impl
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ domain
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── mappers
β”‚Β Β  β”‚Β Β  └── resources
β”‚Β Β  β”‚Β Β  └── local
β”‚Β Β  └── test
β”‚Β Β  └── java
β”‚Β Β  └── com
β”‚Β Β  └── My_Company
β”‚Β Β  └── core
β”‚Β Β  └── backend
β”‚Β Β  β”œβ”€β”€ actuator
β”‚Β Β  β”œβ”€β”€ menu
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ api
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ v1
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”œβ”€β”€ dto
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── response
β”‚Β Β  β”‚Β Β  β”‚Β Β  β”‚Β Β  └── impl
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── v2
β”‚Β Β  β”‚Β Β  β”‚Β Β  └── impl
β”‚Β Β  β”‚Β Β  β”œβ”€β”€ domain
β”‚Β Β  β”‚Β Β  └── mappers
β”‚Β Β  └── util
└── target
└── classes
└── local

Running scaffold command again

Due to the fact that the CLI does quite a lot of work, it will not attempt to create the projects if the project path already exists. For example, running the same command as before, without changing any of the settings will result in an error being displayed during the creation of the project.

stacks-cli scaffold -c ./stacks.yml

Project protection guard

As can be seen the CLI will not overwrite anything at the same target path.

It is possible to change this behaviour, by adding the --force option to the command line. This will remove any existing directory and recreate the project in its place.

Note

If the project directory already exists but it is empty, e.g. it does not contain any files or directories, then the CLI will continue to use the directory and warn that it has done so.

stackscli overwrite empty dir

stacks-cli scaffold -c ./stacks.yml --force

Force removal of existng project directories

Checking Framework command versions

Each project that gets scaffolded by the CLI, has has stackscli.yml file which informs the CLI what to do for that project. One of the things that can be set is constraints on the version of the framework that needs to be installed.

For example take the following project settings file.

framework:
name: dotnet
commands:
- name: dotnet
version: ">= 3.1, < 3.2"


# Pipeline files
pipeline:
- type: azdo
files:
- name: build
path: build/azDevOps/azure/azure-pipelines-netcore-k8s.yml
- name: variable
path: build/azDevOps/azure/azuredevops-vars.yml
replacements:
- pattern: ^.*stacks-credentials-nonprod-kv$
value: ""

# The init stage are things that are required to run before the template is run
init:
operations:
- action: cmd
cmd: dotnet
args: new -i .
desc: Install "stacks-webapi" template from the repo directory
- action: cmd
cmd: dotnet
args: new stacks-webapi -n {{ .Input.Business.Company }}.{{ .Input.Business.Domain }} -o {{ .Project.Directory.WorkingDir }}
desc: Create a project using the "stacks-webapi" template

When the CLI runs it will take take the version constraint, on line 5, and compare the version of dotnet it finds with this constraint. The following screenshot shows this in action on a machine that has .NET version 5.0.303 installed.

Dotnet command version check

It is possible to bypass this version check by using the --force option on the command line, but note this is a destructive operation and if the project exists at the same location as the CLI is trying to write to the original project will be deleted.

In this case the error will still be displayed, but a a warning will state that the process is continuing.

Dotnet command bypass version check