|
2 | 2 |
|
3 | 3 | ## suite-cli: Monorepo CLI Tool (The mono-repo Manager 🦧) |
4 | 4 |
|
| 5 | +### Intro |
| 6 | +- Suite-CLI is a cross-platform easy to use command line interface for managing monorepos. |
| 7 | +- Build and ship quickly with code-generator `suite generate` that helps you scaffold resources so you can focus on the core functionality and reduce project setup overhead. |
| 8 | +- Suite uses consistent and intuitive syntax for commands both in development and CI. |
| 9 | +Example |
| 10 | + ```bash |
| 11 | + yarn workspace @microservices-suite/utilities run dev |
| 12 | + ``` |
| 13 | +The same command with suite-CLI |
| 14 | + ```bash |
| 15 | + suite start utilities |
| 16 | + ``` |
| 17 | +- The CLI uses automation and smart algorithmns to run otherwise repetetive tasks and orchestrate complex workflows with simple commands. |
| 18 | +- Streamline building & publishing docker images |
| 19 | +- Easily maintain and publish private packages to npm registry using `suite {library_name} release` |
| 20 | +- Streamline containerization with docker and scale with kubernetes both in development and production. |
| 21 | + |
5 | 22 | ### Installation |
6 | 23 |
|
7 | 24 | In this guide we describe using `npm` to install packages. Other package managers may be used at your discretion. With npm, you have several options available for managing how your OS command line resolves the location of the `suite CLI` binary file. Here, we describe installing the `suite` binary globally using the -g option. This provides a measure of convenience, and is the approach we assume throughout the documentation. Note that installing any `npm` package globally leaves the responsibility of ensuring they're running the correct version up to the user. It also means that if you have different projects, each will run the same version of the CLI. A reasonable alternative is to use the npx program, built into the npm cli (or similar features with other package managers) to ensure that you run a managed version of the `Suite` CLI. We recommend you consult the npx documentation and/or your DevOps support staff for more information.To install `suite-cli` globally, run the following command: |
8 | 25 |
|
9 | 26 | Install the CLI globally using the `npm install -g` command (see the **Note** above for details about global installs). |
10 | 27 |
|
11 | | -```bash |
12 | | -npm install -g @microservices-suite/cli |
13 | | -``` |
| 28 | + ```bash |
| 29 | + npm install @microservices-suite/cli -g |
| 30 | + ``` |
14 | 31 | **HINT** |
15 | 32 | Alternatively, you can use this command `npx @microservices-suite/cli@latest` without installing the cli globally. |
16 | 33 |
|
| 34 | +### Prerequisites(required) |
| 35 | +- Suite uses `yarn workspaces` to generate and manage your monorepo. You need to install yarn globally to smoothly run our CLI. |
| 36 | + - Install yarn globally(You may need superuser priviledges). |
| 37 | + ```bash |
| 38 | + sudo npm install yarn -g |
| 39 | + ``` |
| 40 | + - Using brew on Mac |
| 41 | + ```bash |
| 42 | + brew install yarn |
| 43 | + ``` |
| 44 | +- In development, suite uses `nodemon` and `symbolic links(symlinks)` to watch your code changes in target files in vanilla mode as well as dockerized apps with mapped volumes. |
| 45 | + ```bash |
| 46 | + sudo npm install nodemon -g |
| 47 | + ``` |
| 48 | +### Prerequisites(optional) |
| 49 | +- To be able to containerize your application you will need to install `docker` on your machine, however, it is not required. You can still run your services in `vanilla mode` using `nodemon` in development mode and `PM2` in production. |
| 50 | + - Install docker for Linux 👉 [here ](https://docs.docker.com/desktop/install/linux-install/) |
| 51 | + - Install docker for Mac 👉 [here ](https://docs.docker.com/desktop/install/mac-install/) |
| 52 | + - Install docker for Windows 👉 [here ](https://docs.docker.com/desktop/install/windows-install/) |
| 53 | +- To simulate scaling with kubernetes on your local machine you will need to install `minikube,kubectl,virtul machine(virtualBox)` |
| 54 | + - Install your platform's VirtualBox binary 👉 [here ](https://www.virtualbox.org/wiki/Downloads) |
| 55 | + - Install your platform's minikube binary 👉 [here ](https://minikube.sigs.k8s.io/docs/start/) |
| 56 | + - Install `kubectl` the CLI for communicating with kubernetes clusters within the Virtual Machine which simulates one development node configured by `minikube` |
| 57 | + - Linux binary |
| 58 | + ```bash |
| 59 | + https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/ |
| 60 | + ``` |
| 61 | + - Mac(Intel chip) binary |
| 62 | + ```bash |
| 63 | + curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl" |
| 64 | + ``` |
| 65 | + - Windows binary |
| 66 | + ```bash |
| 67 | + curl.exe -LO "https://dl.k8s.io/release/v1.30.0/bin/windows/amd64/kubectl.exe" |
| 68 | + ``` |
| 69 | +- Install `PM2` to run your components in prod |
| 70 | + ```bash |
| 71 | + npm install pm2 -g |
| 72 | + ``` |
| 73 | + |
17 | 74 | ### Basic workflow |
18 | 75 | - Once installed, you can invoke CLI commands directly from your OS command line through the `suite` executable. See the available `suite` commands by entering the following: |
19 | | -```bash |
20 | | -suite --help |
21 | | -``` |
22 | | - |
23 | | -- Get help on an individual command using the following construct. Substitute any command, like `host`, `docker:start`, etc., where you see `start` in the example below to get detailed help on that command: |
24 | | -```bash |
25 | | -suite start --help |
26 | | -``` |
| 76 | + ```bash |
| 77 | + suite --help |
| 78 | + ``` |
27 | 79 |
|
28 | 80 | ### Scaffold new repo |
29 | 81 | - Suite-CLI can help you quickly initialize a new monorepo project and save you alot of project setup and devops overhead. The new project comes ready with our standard file structure with version control and workspaces configured to start code sharing and realize the full power of symlinking: |
30 | | -```bash |
31 | | -suite generate |
32 | | -``` |
| 82 | + ```bash |
| 83 | + suite generate |
| 84 | + ``` |
33 | 85 |
|
34 | 86 | - This is an interactive command that progressively builds the project by selecting options for the name, API architecture to work with, webservers of choice and more. |
35 | 87 | - When done generating your project you can still generate other components piece-wise like microservice, library or workspace. This makes your development work easier as it automatically builds your package.json or better yet generates a valid workspace compatible with the current project. |
36 | 88 |
|
37 | 89 | ### Install dependencies at workspace |
38 | 90 | - This command lets you install dependencies with more control for where to install. This leverages no-hoisting feature to deliver symlinking close to the relevant workspace. |
39 | | -```bash |
40 | | -suite add <@microservices-suite/<workspace_name>> express axios |
41 | | -``` |
| 91 | + ```bash |
| 92 | + suite add <@microservices-suite/<workspace_name>> express axios |
| 93 | + ``` |
42 | 94 |
|
43 | 95 | ### Docker instances management |
44 | 96 | - Suite has abstracted away the complexity of working with `docker compose` and `vanilla docker` commands in monorepo environment by using `suite's` concise and consistent syntax |
45 | 97 | - Run `docker volume|system prune -f` |
46 | | -```bash |
47 | | -suite prune [-fav] |
48 | | -``` |
| 98 | + ```bash |
| 99 | + suite prune [-fav] |
| 100 | + ``` |
49 | 101 | - This command works behaves exactly as docker and if `[-v-a]` flags are passed they specify you are targeting `volumes or al(volumes & system)`. |
50 | 102 | - This is part of house keeping that suite exposes to clean up your environemnt when its blotted with dangling images or containers and volumes. |
51 | | -```bash |
52 | | -suite docker:start |
53 | | -``` |
| 103 | + ```bash |
| 104 | + suite docker:start |
| 105 | + ``` |
54 | 106 | - Start all services in vanilla mode |
55 | 107 | - If mode is not specified this command spins services in development environment |
56 | 108 | - The mode must match the env extension `.env.[mode]` except production `.env` which does not have an extension |
57 | 109 | - you can pass services to start separated with spaces eg `suite start -v supplier-service customer-service` |
58 | 110 | - If no services are specified suite spins all services in the `@microservices-suite` workspace |
59 | | -```bash |
60 | | -suite start -v <...services> |
61 | | -``` |
| 111 | + ```bash |
| 112 | + suite start -v <...services> |
| 113 | + ``` |
62 | 114 | - Start services with docker compose |
63 | 115 | - If mode is not specified this command spins services in development environment |
64 | 116 | - The mode must match the env extension `.env.[mode]` except production `.env` which does not have an extension |
65 | 117 | - you can pass services to start separated with spaces eg `suite start -v supplier-service customer-service` |
66 | 118 | - If no services are specified suite spins all services in the `@microservices-suite` workspace |
67 | | -```bash |
68 | | -suite start <service-name...> |
69 | | -``` |
| 119 | + ```bash |
| 120 | + suite start <service-name...> |
| 121 | + ``` |
70 | 122 | ### Package management and release |
71 | 123 | - To easily release your builds and generate changelogs, suite makes it easy using `suite release` command |
72 | 124 | - To publish to npm registry any shared libray simply run the `suite release` passing the name of the library |
73 | 125 | - Suite will automatically figure out what library in your workspace you are targeting and initiate an interactive release workflow where you will specify the semver. |
74 | 126 | - To run this command succesfully you need to create one `automation & publish` `auth_token` on your private registry and then run `npm or yarn login` |
75 | | -```bash |
76 | | -suite release [package] |
77 | | -``` |
| 127 | + ```bash |
| 128 | + suite release [package] |
| 129 | + ``` |
0 commit comments