Merge pull request #17 from aws-samples/code-quality

Added instructions for contributing new Node Runners blueprints

README.md

@@ -1,25 +1,25 @@
 # AWS Blockchain Node Runners
 
-This repository contains sample [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) applications (Node Runner blueprints) to deploy on AWS self-service blockchain nodes for various protocols. For more information see [Introducing AWS Blockchain Node Runners](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro).
+This repository contains sample [AWS Cloud Development Kit (CDK)](https://aws.amazon.com/cdk/) applications (Node Runner Blueprints) to deploy on AWS self-service blockchain nodes for various protocols. For more information see [Introducing AWS Blockchain Node Runners](https://aws-samples.github.io/aws-blockchain-node-runners/docs/intro).
 
 ### Documentation
 For deployment instructions see [AWS Blockchain Node Runners Blueprints](https://aws-samples.github.io/aws-blockchain-node-runners/docs/Blueprints/intro)
 
-### Contributing
-See [CONTRIBUTING](./CONTRIBUTING.md) for more information.
+### Adding blueprints for new nodes
+
+If you'd like propose a Node Runner Blueprint for your node see [Adding new Node Runner Blueprints](./docs/adding-new-nodes.md)
 
 ### Directory structure
 
-- `docs` - General documentation applicable to all Node Runner blueprints (CDK applications within the `./lib` directory)
-- `lib` - The place for all Node Runner blueprints and shared re-usable [CDK constructs](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html)
-- `lib/constructs` - [CDK constructs](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html) used in Node Runner blueprints
-- `lib/your-chain` - Node Runner blueprint for a specific chain
-- `lib/your-chain/doc` - Documentation specific to the Node Runner blueprint
-- `lib/your-chain/lib` - Place for CDK stacks and other blueprint assets
-- `lib/your-chain/sample-configs` - Place for sample configurations to deploy Node Runner blueprint to your environment
-- `lib/your-chain/test` - Place for unit tests to verify the Node Runner blueprint creates all necessary infrastructure
+- `docs` - General documentation applicable to all Node Runner Blueprints (CDK applications within the `./lib` directory)
+- `lib` - The place for all Node Runner Blueprints and shared re-usable [CDK constructs](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html)
+- `lib/constructs` - [CDK constructs](https://docs.aws.amazon.com/cdk/v2/guide/constructs.html) used in Node Runner Blueprints
+- `lib/your-chain` - Node Runner Blueprint for a specific chain
 - `website` - Content for the project web site built with [Docusaurus](https://docusaurus.io/)
-- `website/docs` - Place for the new blueprint deployment instructions. (If you are adding a new blueprint, use on of the existing examples to refer to the `README.md` file within your Node Runner blueprint directory inside `lib`).
+- `website/docs` - Place for the new blueprint deployment instructions. (If you are adding a new blueprint, use on of the existing examples to refer to the `README.md` file within your Node Runner Blueprint directory inside `lib`).
 
 ### License
 This repository uses MIT License. See more in [LICENSE](./LICENSE)
+
+### Contributing
+See [CONTRIBUTING](./CONTRIBUTING.md) for more information.

docs/adding-new-nodes.md

@@ -0,0 +1,34 @@
+# Adding Node Runner Blueprints
+
+First of all, THANK YOU! The easier it is to run a blockchain node on AWS the simpler it is for the ecosystem to build with it. Here are the major steps to contribute a Node Runner Blueprint:
+
+1. Check with our list of [Issues](https://github.com/aws-samples/aws-blockchain-node-runners/issues) if someone is already working on the node type you are after. If yes - join the forces! If no, go to the next step.
+2. Create a new issue to propose a new node type to let everyone know that you are going ot work on it. Use `Feature request` template for that.
+3. [Fork this repository](https://help.github.com/articles/fork-a-repo/).
+4. Use one of the existing blueprints as a baseline. Choose the one that has architecture closest to the one you want to create.
+5. Once you are happy with how your blueprint works, follow our [CONTRIBUTION GUIDE](../CONTRIBUTING.md) to create a [pull request](https://help.github.com/articles/creating-a-pull-request/) for our team to review it.
+6. Once merged, let your community know that the new Node Runner Blueprint is ready for them to use!
+
+### Recommended directory and file structure for a Node Runner Blueprint
+
+- `lib/your-chain/doc/` - Documentation specific to the Node Runner Blueprint
+- `lib/your-chain/lib/` - Place for CDK stacks and other blueprint assets
+- `lib/your-chain/lib/assets/` - Place for everything that needs to be within the provisioned EC2 instance (user-data scripts, docker-compose files, etc.)
+- `lib/your-chain/lib/config/` - Your version of the config reader to parse values from `.env` file
+- `lib/your-chain/lib/constructs/` - All CDK constructs specific to this  Node Runner Blueprint
+- `lib/your-chain/lib/*-stack.ts` - All [CDK stacks](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html) for this Node Runner Blueprint
+- `lib/your-chain/sample-configs/` - Place for sample configurations to deploy Node Runner Blueprint to your environment
+- `lib/your-chain/test/` - Place for unit tests to verify the Node Runner Blueprint creates all necessary infrastructure
+- `lib/your-chain/.env-sample` - A sample configuration file
+- `lib/your-chain/app.ts` - Entry point to your AWS CDK application
+- `lib/your-chain/cdk.json` - Config file for [feature flags](https://docs.aws.amazon.com/cdk/v2/guide/featureflags.html) for your AWS CDK application
+- `lib/your-chain/jest.config.json` - [Configuration file for Jest](https://jestjs.io/docs/configuration)
+- `lib/your-chain/README.md` - All information and usage instructions for your Node Runner Blueprint
+
+### Reusable imports and CDK constructs for stacks in Node Runner Blueprints
+
+- `lib/constructs/config.interface.ts` - Interface classes to implement your own configuration module. Compatible with `ha-rpc-nodes-with-alb` and `single-node` constructs (see below).
+- `lib/constructs/constants.ts` - Useful constants to use in configuration files and to set up infrastructure.
+- `lib/constructs/ha-rpc-nodes-with-alb.ts` - Provisions up to 4 identical EC2 instances to run nodes managed by an Auto Scaling Group and behind an Application Load Balancer.
+- `lib/constructs/single-node.ts` - Creates a single EC2 instance to run a blockchain node.
+- `lib/constructs/snapshots-bucket.ts` - Creates an S3 bucket to store a copy of blockchain node state to speed up syncing process.

website/docs/Blueprints/intro.md

@@ -3,8 +3,43 @@ sidebar_position: 1
 sidebar_label: About blueprints
 ---
 
-# About blueprints
+# Node Runners Blueprints
 
-Blueprints are TypeScrypt application built with [AWS Cloud Development Kit](https://aws.amazon.com/cdk/). They are infrastructure as code apps that you can use to deploy blockchain nodes in different configurations be it solo nodes or highly available setups. Most of the apps will look into `.env` file in its root directory for input params to know which compute, storage and node setup options to use during deployment.
+Node Runner Blueprints are TypeScrypt applications built with [AWS Cloud Development Kit](https://aws.amazon.com/cdk/). They are infrastructure as code apps that you can use to deploy to AWS blockchain nodes in different configurations be it solo nodes or highly available setups. Most of the apps will look into `.env` file in its root directory for input params to know which compute, storage and node setup options to use during deployment.
 
-👈 Use navigation bar on the left for setting up nodes for different protocols.
+👈 Use navigation bar on the left for the setup guides for different protocols.
+
+## Adding new Node Runner Blueprints
+
+First of all, THANK YOU! The easier it is to run a blockchain node on AWS the simpler it is for the ecosystem to build with it. Here are the major steps to contribute a Node Runner Blueprint:
+
+1. Check with our list of [Issues](https://github.com/aws-samples/aws-blockchain-node-runners/issues) if someone is already working on the node type you are after. If yes - join the forces! If no, go to the next step.
+2. Create a new issue to propose a new node type to let everyone know that you are going ot work on it. Use `Feature request` template for that.
+3. [Fork this repository](https://help.github.com/articles/fork-a-repo/).
+4. Use one of the existing blueprints as a baseline. Choose the one that has architecture closest to the one you want to create.
+5. Once you are happy with how your blueprint works, follow our [Contribution Guide](https://github.com/aws-samples/aws-blockchain-node-runners/blob/main/CONTRIBUTING.md) to create a [pull request](https://help.github.com/articles/creating-a-pull-request/) for our team to review it.
+6. Once merged, let your community know that the new Node Runner Blueprint is ready for them to use!
+
+### Recommended directory and file structure for a Node Runner Blueprint
+
+- `lib/your-chain/doc/` - Documentation specific to the Node Runner Blueprint
+- `lib/your-chain/lib/` - Place for CDK stacks and other blueprint assets
+- `lib/your-chain/lib/assets/` - Place for everything that needs to be within the provisioned EC2 instance (user-data scripts, docker-compose files, etc.)
+- `lib/your-chain/lib/config/` - Your version of the config reader to parse values from `.env` file
+- `lib/your-chain/lib/constructs/` - All CDK constructs specific to this  Node Runner Blueprint
+- `lib/your-chain/lib/*-stack.ts` - All [CDK stacks](https://docs.aws.amazon.com/cdk/v2/guide/stacks.html) for this Node Runner Blueprint
+- `lib/your-chain/sample-configs/` - Place for sample configurations to deploy Node Runner Blueprint to your environment
+- `lib/your-chain/test/` - Place for unit tests to verify the Node Runner Blueprint creates all necessary infrastructure
+- `lib/your-chain/.env-sample` - A sample configuration file
+- `lib/your-chain/app.ts` - Entry point to your AWS CDK application
+- `lib/your-chain/cdk.json` - Config file for [feature flags](https://docs.aws.amazon.com/cdk/v2/guide/featureflags.html) for your AWS CDK application
+- `lib/your-chain/jest.config.json` - [Configuration file for Jest](https://jestjs.io/docs/configuration)
+- `lib/your-chain/README.md` - All information and usage instructions for your Node Runner Blueprint
+
+### Reusable imports and CDK constructs for stacks in Node Runner Blueprints
+
+- `lib/constructs/config.interface.ts` - Interface classes to implement your own configuration module. Compatible with `ha-rpc-nodes-with-alb` and `single-node` constructs (see below).
+- `lib/constructs/constants.ts` - Useful constants to use in configuration files and to set up infrastructure.
+- `lib/constructs/ha-rpc-nodes-with-alb.ts` - Provisions up to 4 identical EC2 instances to run nodes managed by an Auto Scaling Group and behind an Application Load Balancer.
+- `lib/constructs/single-node.ts` - Creates a single EC2 instance to run a blockchain node.
+- `lib/constructs/snapshots-bucket.ts` - Creates an S3 bucket to store a copy of blockchain node state to speed up syncing process.

website/docs/intro/intro.md

@@ -10,7 +10,7 @@ Our journey began with research projects and testing conducted within AWS. As we
 
 The AWS Solutions Architects involved in this project pour their hearts into it, all while juggling their primary job responsibilities. Their passion for blockchain technology drives them to provide the best possible support for this initiative. We're excited to have you on board and look forward to making the blockchain world more accessible together! 😊
 
-We welcome contributions from both enthusiasts like us or established blockchain organizations, which many of our customers are. You can report bugs, create pull requests, add support for new nodes or new infrastructure configurations for existing ones. Please have a look at our [Contribution Guide](https://github.com/aws-samples/aws-blockchain-node-runners/blob/solana/CONTRIBUTING.md).
+We welcome contributions from both enthusiasts like us or established blockchain organizations, which many of our customers are. You can report bugs, create pull requests, add support for new nodes or new infrastructure configurations for existing ones. Please have a look at our [Contribution Guide](https://github.com/aws-samples/aws-blockchain-node-runners/blob/main/CONTRIBUTING.md).
 
 ## Code of Conduct
 This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).