update docs

mantil-io · Mar 9, 2022 · 964df06 · 964df06
1 parent 5959b7b
commit 964df06
Show file tree

Hide file tree

Showing 15 changed files with 359 additions and 255 deletions.
diff --git a/docs/analytics.md b/docs/analytics.md
@@ -0,0 +1,13 @@
+
+# Anonymous Analytics
+
+Every execution of the Mantil CLI sends an [CliCommand](https://github.com/mantil-io/mantil/blob/4ef981e9c89025f3ebcd3937b4872071caafb80e/domain/event.go#L22) piece of data. It contains metrics about the current Mantil workspace, stage, project and series of [Events](https://github.com/mantil-io/mantil/blob/4ef981e9c89025f3ebcd3937b4872071caafb80e/domain/event.go#L35) which are command-specific. Look into the definition of the [Event](https://github.com/mantil-io/mantil/blob/4ef981e9c89025f3ebcd3937b4872071caafb80e/domain/event.go#L109) to get the feeling about what data we collect.
+
+For example, for [Deploy](https://github.com/mantil-io/mantil/blob/4ef981e9c89025f3ebcd3937b4872071caafb80e/domain/event.go#L128) command, we collect metrics about how many Lambda functions are added, updated and removed during the deploy command execution. Further, we collect durations of the build, upload and update phases. How many bytes were transferred to the S3 bucket and whether it was just function updates or we made some infrastructure changes (new function, API gateway).
+
+Events are collected anonymously with the primary purpose of helping us understand how people use Mantil and allowing us to prioritize fixes and features as well as to catch errors as soon as those happen. We are a small team with the product in early beta and would really appreciate keeping the events collection on. However, if you are working on a super-secret government project, there is an option to disable them by setting [MANTIL_NO_EVENTS](https://github.com/mantil-io/mantil/blob/5d0ee4a609a63821eb319776c9981af6e0df4049/domain/workspace.go#L33) environment variable. Internally we use it just when running integration tests.
+
+We also pay special attention to the kind of data we are collecting, so,  e.g., if you put your AWS credentials into the command line, we recognize that and [remove](https://github.com/mantil-io/mantil/blob/4ef981e9c89025f3ebcd3937b4872071caafb80e/domain/event.go#L213) them.
+
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
diff --git a/docs/api.md b/docs/api.md
@@ -47,3 +47,5 @@ Each API can be accessed via WebSocket which is useful for applications that nee
 For client-side use we provide a [JavaScript SDK](https://github.com/mantil-io/mantil.js).
 
 A complete example on how to use the WebSocket API can be found in the [chat](https://github.com/mantil-io/template-chat) template.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
diff --git a/docs/api_configuration.md b/docs/api_configuration.md
@@ -1,8 +1,10 @@
 # API Configuration
 
-APIs come preconfigured with some default settings for memory size, timeout and environment variables. You can customize these settings using the `config/environment.yml` file. Values can be defined on a project, stage or function level. If the same value is defined on multiple levels the lowest level will take precedence. The final values will be visible in `config/state.yml` after deployment.
+## Environment Variables
 
-For example, let's say we created a project with two functions called `one` and `two` and deployed it to two stages called `development` and `production`. After creating both stages the `config/state.yml` file will look like this:
+APIs come preconfigured with default settings for memory size, timeout and environment variables. You can customize these settings using the `config/environment.yml` file. Values can be defined on a project, stage or function level. If the same value is defined on multiple levels, the lowest level will take precedence. The final values will be visible in `config/state.yml` after deployment.
+
+For example, let's say we created a project with two functions called `one` and `two` and deployed it to two stages called `development` and `production`. After creating both stages, the `config/state.yml` file will look like this:
 ```
 name: my-project
 stages:
@@ -49,7 +51,7 @@ stages:
       MANTIL_PROJECT: my-project
       MANTIL_STAGE: production
 ```
-Since we have not yet defined any custom values in `config/environment.yml` all values will be set to their defaults. Note that Mantil also sets some default environment variables which always start with `MANTIL_`. Now we can define some custom values:
+Since we have not yet defined any custom values in `config/environment.yml` all values will be set to their defaults. Note that Mantil also sets some default environment variables, always starting with `MANTIL_`. So now we can define some custom values:
 ```
 project:
   memory_size: 128
@@ -71,7 +73,7 @@ project:
       env:
         KEY: stage
 ```
-Now after deploying both stages again the final state will look like this:
+After deploying both stages again the final state will look like this:
 ```
 name: my-project
 stages:
@@ -123,10 +125,13 @@ stages:
       MANTIL_PROJECT: my-project
       MANTIL_STAGE: production
 ```
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
 
 ## Scheduled execution
 
-Using the `cron` field you can set up a rule to execute an API on a schedule. For example, with the following setup the default method of the `one` API will be executed every minute:
+Using the `cron` field, you can set up a rule to execute an API on a schedule. For example, with the following setup, the default method of the `one` API will be executed every minute:
 ```
 project:
   stages: 
@@ -137,16 +142,24 @@ project:
         env:
           KEY: function
 ```
-For more information about the cron syntax please refer to the AWS docs:
+For more information about the cron syntax, please refer to the AWS docs:
 https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/RunLambdaSchedule.html
 
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
 ## Private APIs
 
-Using the `private` field you can set your functions as private which will then require additional authorization for the execution of methods through API. Private and public keys are generated during creation of new stage which are then used to generate JWT on each request. This token is verified through authorizer lambda function. Token generation is done automatically if you're using `invoke` command.
+Using the `private` field, you can set your functions as private, which will require additional authorization to execute methods through API. Private and public keys are generated when creating a new stage which are then used to generate JWT on each request. This token is verified through the authorizer Lambda function. Token generation is done automatically if you're using the `invoke` command.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
 
 ## Custom domain names
 
-Custom domain names are simpler and more intuitive URLs that you can provide to your API users. By default, you can access APIs through the default API gateway URLs which are generated for each stage and have the following format:
+Custom domain names are simpler and more intuitive URLs that you can provide to your API users. By default, you can access APIs through the default API gateway URLs, which are generated for each stage and have the following format:
 ```
 https://<http-api-id>.execute-api.<region>.amazonaws.com/<api_name>/<method_name>
 ```
@@ -183,3 +196,5 @@ and
 ```
 wss://ws.example.com
 ```
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
diff --git a/docs/aws_install.md b/docs/aws_install.md
@@ -0,0 +1,139 @@
+# Detailed AWS Setup
+
+Mantil consists of two main components, node and CLI. [CLI](cli_install.md) is the Mantil binary you
+install on your local machine while the node is located in AWS. A node consists of Lambda functions and other AWS resources used for managing Mantil projects in the cloud and will be explained in detail in the upcoming chapter.
+
+## AWS Account
+You need to bring your own AWS account to work with Mantil. However, if you don't have one, you can easily create it by following [AWS instructions](https://portal.aws.amazon.com/billing/signup#/start). To install a node into your AWS account Mantil requires account credentials with IAM `AdministratorAccess` privileges. 
+
+Mantil will never store your credentials; those are only used to set up a node into an AWS account. After the node is installed, all other communication is between the Mantil command line and the node. That means that node install/uninstall phases are the only time you need to provide AWS account credentials. 
+
+Node functions have only necessary IAM permissions. All the resources created for the Mantil node (API Gateway, Lambda function, IAM roles) have the 'mantil-' prefix. You can list node resources by the `mantil aws resources` command.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
+## Mantil Node Setup
+AWS credentials are needed just for initial setting up Mantil in your account.
+After the initial setup, the other commands won't need your AWS credentials.
+
+To install Mantil in a region of an AWS account, use `mantil aws install`. This
+will create Mantil
+[node](https://github.com/mantil-io/mantil/blob/master/docs/concepts.md#node) in
+your AWS account. A node consists of a set of Lambda functions, API Gateway and a
+S3 bucket. After the node is created, all other communication is between the CLI and
+the node. 
+
+Mantil is not storing your AWS credentials; they are only used during node
+install and later uninstall. 
+
+You can provide AWS credentials in three different ways:
+
+- As command line arguments:
+
+```
+mantil aws install --aws-access-key-id=AKIAIOSFODNN7EXAMPLE \
+                   --aws-secret-access-key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
+                   --aws-region=us-east-1
+```
+
+- Set [environment
+  variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)
+  AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION and instruct
+  Mantil to use that environment:
+
+```
+export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+export AWS_DEFAULT_REGION=us-east-1
+mantil aws install --aws-env
+```
+
+- Allow Mantil to use a [named
+  profile](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)
+  from your AWS configuration (~/.aws/config):
+
+```
+mantil aws install --aws-profile=my-named-profile
+```
+
+Install action usually less than 2 minutes to complete.  
+After install `mantil aws nodes` command will show that node: 
+
+```
+➜ mantil aws nodes
+| NAME | AWS ACCOUNT  |  AWS REGION  |    ID    | VERSION |
+|------|--------------|--------------|----------|---------|
+| demo | 052548195718 | eu-central-1 | 7582352e | v0.2.5  |
+```
+
+A node is located in a region of an AWS account. You can have multiple nodes in the same or different account.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
+## Created Resources
+To see what resources are created for the node run `mantil aws resources` command:
+```
+➜ mantil aws resources
+
+Node demo
+Resources:
+|    NAME    |         TYPE         |     AWS RESOURCE NAME      |               CLOUDWATCH LOG GROUP               |
+|------------|----------------------|----------------------------|--------------------------------------------------|
+| setup      | Lambda Function      | mantil-setup-7582352e      | /aws/lambda/mantil-setup-7582352e                |
+| authorizer | Lambda Function      | mantil-authorizer-7582352e | /aws/lambda/mantil-authorizer-7582352e           |
+| deploy     | Lambda Function      | mantil-deploy-7582352e     | /aws/lambda/mantil-deploy-7582352e               |
+| destroy    | Lambda Function      | mantil-destroy-7582352e    | /aws/lambda/mantil-destroy-7582352e              |
+| security   | Lambda Function      | mantil-security-7582352e   | /aws/lambda/mantil-security-7582352e             |
+| setup      | CloudFormation Stack | mantil-setup-7582352e      |                                                  |
+| http       | API Gateway          | mantil-http-7582352e       | /aws/vendedlogs/mantil-http-access-logs-7582352e |
+|            | S3 Bucket            | mantil-7582352e            |                                                  |
+Tags:
+|       KEY        |         VALUE          |
+|------------------|------------------------|
+| MANTIL_KEY       | 7582352e               |
+| MANTIL_WORKSPACE | LhvoKl2bQEib2UFhs7ypIA |
+```
+
+All node resources have prefix 'mantil-' in the name and a random suffix. 
+Node consist of few Lambda functions, CloudFormation stack, API Gateway, S3 bucket and CloudWatch log groups.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
+## Supported AWS Regions
+Mantil is using [Graviton (ARM) powered](https://aws.amazon.com/blogs/aws/aws-lambda-functions-powered-by-aws-graviton2-processor-run-your-functions-on-arm-and-get-up-to-34-better-price-performance/) Lambda functions. Mantil is available in every region where Graviton Lambda functions are [supported](https://github.com/mantil-io/mantil/blob/eafd1a09bade875e225b5f271cdb17f9211a970a/cli/controller/setup.go#L30):
+
+> US East (N. Virginia), US East (Ohio), US West (Oregon), Europe (Frankfurt), Europe (Ireland), EU (London), Asia Pacific (Mumbai), Asia Pacific (Singapore), Asia Pacific (Sydney), Asia Pacific (Tokyo).
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
+## AWS Costs
+For trying Mantil, you can for sure stay within [free tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) of all the AWS services. You have pretty generous monthly limits for many services when you create a new AWS account. The two most important you will use with Mantil are Lambda functions and API Gateway. Here are their free tier monthly limits:
+
+> The Amazon API Gateway free tier includes one million API calls received for REST APIs, one million API calls received for HTTP APIs, and one million messages and 750,000 connection minutes for WebSocket APIs per month for up to 12 months.
+
+> The AWS Lambda free tier includes one million free requests per month and 400,000 GB-seconds of compute time per month.
+
+Until you don't have some significant user base or are not mining bitcoins in your Lambda function, you will for sure stay within the limits of the free tier. So trying Mantil will cost you nothing. 
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+#
+
+## Uninstall
+Uninstall command `mantil aws uninstall` will clean up all created resources and leave the AWS account in the initial state.
+At this step, you will need to provide your AWS credentials again. There are three possible ways to do so that are already described in the node setup. 
+
+After the uninstall, your account is in its original state. Mantil will remove anything it created.
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
+
+
+
diff --git a/docs/installation.md → docs/cli_install.md b/docs/installation.md → docs/cli_install.md
@@ -1,6 +1,9 @@
-## Installation
+# Mantil CLI Installation
 
-### Homebrew (Mac and Linux)
+Mantil consists of two main components, node and CLI. CLI is the Mantil binary you
+install on your local machine while [the node](aws_install.md) is located in AWS. To install CLI, follow the steps below for your OS.
+
+## Homebrew (Mac and Linux)
 
 Use [Homebrew](https://brew.sh) to install the latest version:
 
@@ -9,7 +12,7 @@ brew tap mantil-io/mantil
 brew install mantil
 ```
 
-### Direct Download (Linux, Windows and Mac)
+## Direct Download (Linux, Windows and Mac)
 
 Below are the available downloads for the latest version of Mantil. Please
 download the right package for your operating system and architecture.
@@ -36,3 +39,6 @@ wget https://s3.eu-central-1.amazonaws.com/releases.mantil.io/latest/mantil_Linu
 tar xvfz mantil_Linux_x86_64.tar.gz
 mv mantil /usr/local/bin
 ```
+
+
+<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>
Original file line number	Diff line number	Diff line change
Expand Up		@@ -47,3 +47,5 @@ Each API can be accessed via WebSocket which is useful for applications that nee
		For client-side use we provide a [JavaScript SDK](https://github.com/mantil-io/mantil.js).

		A complete example on how to use the WebSocket API can be found in the [chat](https://github.com/mantil-io/template-chat) template.

		<p align="right"> <a href="https://github.com/mantil-io/mantil/tree/master/docs#documentation">↵ Back to Documentation Home!</a></p>