diff --git a/OLD-README.md b/OLD-README.md deleted file mode 100644 index 715bda511..000000000 --- a/OLD-README.md +++ /dev/null @@ -1,278 +0,0 @@ -# Commit0 [POC] - -**NOTE** πŸ›‘ This is a proof of concept application. Before you start using this -tool please talk to the team in the `#product-commit0` slack channel so we can -give you better instructions on how to get started. - -[![Build Status](https://travis-ci.org/commitdev/commit0.svg)](https://travis-ci.org/commitdev/commit0) -[![Go Report Card](https://goreportcard.com/badge/github.com/commitdev/commit0?style=flat-square)](https://goreportcard.com/report/github.com/commitdev/commit0) -[![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/commitdev/commit0) - -Status: Proof of Concept - -## About Commit0 -Commit0 is a project skaffolding framework and ecosystem created to: - -1. Maximize knowledge sharing across an organization -2. Easily maintain a state of the art and easily reusable implementations of production grade solutions to recurring problems -3. Re-create the seamless deployment experience offered by PaaS solutions but with a fully open source stack that follows industry best practices - -With Commit0: -- Easily deploy and integrate various boilerplate solutions -- Instantly integrate commonly used open source microservices for authentication, user management, file encryption, image resizing etc. -- Get a simple Push-To-Deploy workflow that you are accustomed to with popular PaaS solutions [TODO] -- There's no vendor lock-in. It's all implemented with open source tools and deployed to your own cloud provider. - -## Commit0 Generator CLI -Commit0 CLI is an opinionated, yet fully modular code generation tool with declarative syntax that allows developers to easily integrate user prompts and interactions. - -Problems we encountered: -- It was tedious to create reusable templates and hard to maintain -- Lack of standardization and integration interface between the templates -- Difficult to integrate individually templated codebases - -How we aim to address those issues: -- Make templating behaviour simple and declarative -- Clear strategy and guideline around what are clear and reusable templates -- Standardize how templated code should get dependent parameters and start up - -This is inspired by: -- [Yeoman Generator](https://github.com/yeoman/generator) -- [JHipster](https://github.com/jhipster/generator-jhipster) -- [Boilr](https://github.com/tmrts/boilr) - - -## Installation - -As there some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. -The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: -`alias commit0='docker run -it -v "$(pwd):/project" -v "${HOME}/.aws:/root/.aws" commit0:v0'` - -# Usage - -1) To create a project run `commit0 create [PROJECT_NAME]` -2) It will prompt you to select a cloud provider and an account profile to use -3) A folder `PROJECT_NAME` will be created. You can `cd [PROJECT_NAME]` and configure the example `commit0.yml` that's generated -4) Run `commit0 generate -c ` to generate all the all the project repos -5) You can go to each project repo and follow the project readme to start the service -6) `commit0 ui` launches the locally hosted web UI (Static SPA) and the API server - - -## Configuring Commit0 - -This is a guide on how to configure your project manually with a single file `commit0.yml`. Simply write this file to the root of your project directory and run the commit0 CLI tool against it to generate your project files. - -* [commit0.yml](#commit0-yaml) - * [name*](#name) - * [context](#context) - * [modules*](#modules) - * [source*](#module-source) - * [params*](#module-params) - * [output](#module-output) - * [overwrite](#module-overwrite) -* [commit0.module.yml](#commit0-module-yaml) - * [name*](#module-name) - * [description](#module-description) - * [prompts](#module-prompts) - * [field*](#prompt-field) - * [label](#prompt-label) - * [options](#prompt-options) - * [template](#template) - * [extension](#template-extension) - * [delimiters](#template-delimiters) - * [output](#template-output) - -## Commit0.yaml -Your project config file. It describes the project -Example: -``` -name: newProject -context: - cognitoPoolID: xxx -modules: - - source: "github.com/commitdev/commit0-aws-eks-stack" - output: "infrastructure" - - source: "github.com/zthomas/react-mui-kit" - output: "web-app" -``` - -## Name -Name of your project. This will be used to name the github repos as well as in other parts of the generated code. - -[]() | | ---- | --- -Required | True -Type | String - -## Context -A key value map of global context parameters to use in the templates. - -[]() | | ---- | --- -Required | False -Type | Map[String] - -## Modules -List of modules template modules to import - -[]() | | ---- | --- -Required | True -Type | Map[Module] - -## Source -We are using go-getter to parse the sources, we you can use any URL or file formats that [go-getter](https://github.com/hashicorp/go-getter#url-format) supports. - -[]() | | ---- | --- -Required | True -Type | String - -## Params -Module parameters to use during templating - -[]() | | ---- | --- -Required | True -Type | String - -## Output -Template output directory that the current module should write to. - -[]() | | ---- | --- -Required | False -Type | String - -## Overwrite -Whether to overwrite existing files when generating files from templates - -[]() | | ---- | --- -Required | False -Type | Boolean -Default | False - - -## Commit0.module.yaml -The module config file. You can configure how the templating engine should process the files in the current repository. -Example: -``` -name: react-mui-kit -template: - extension: '.tmplt' - delimiters: - - '<%' - - '%>' - output: web-app -``` - -## Name -Name of your module. This will be used as the default module directory as well as a display name in the prompts. - -[]() | | ---- | --- -Required | True -Type | String - -## Description -Short description of the module - -[]() | | ---- | --- -Required | False -Type | String - -## template -Template configurations -[]() | | ---- | --- -Required | False -Type | Map - -## Extension -File extension to signify that a file is a template. If this is defined, non-template files will not be parsed and will be copied over directly. The default value is `.tmplt` - -[]() | | ---- | --- -Required | False -Type | Map - -## Delimiters -An pair of delimiters that the template engine should use. The default values are: `{{`, `}}` - -[]() | | ---- | --- -Required | False -Type | Map[String] - -## Output -The default template output directory that you want the template engine to write to. This will be overwritten by the - -[]() | | ---- | --- -Required | False -Type | String - -## Prompts -User prompts to generate to collect additional module specific params -[]() | | ---- | --- -Required | False -Type | Map - -## Field -The name of the field that the param should be written to - -[]() | | ---- | --- -Required | True -Type | String - -## Label -The message that will be presented to the user - -[]() | | ---- | --- -Required | False -Type | String - -## Options -A list of options to select from. If not given, then it will be rendered as a text input prompt. - -[]() | | ---- | --- -Required | False -Type | Map[String] - -# Development -We are looking for contributors! - -Building from the source -``` -make install-go -``` -Compile a new `commit0` binary in the working directory -``` -make build -``` - -Now you can either add your project directory to your path or just execute it directly -``` -mkdir tmp -cd tmp -../commit0 create test-app -cd test-app -../../commit0 generate -c commit0.yml -``` - -To run a single test for development -``` -go test -run TestGenerateModules "github.com/commitdev/zero/internal/generate" -v -``` - -### Building locally -As there are some dependencies it will be easier to use this tool within the provided image, clone the repo and then run `make build-docker-local`. - -The best way then to use this is to add an alias, then you can use the CLI as if it was installed as usual on your machine: -`alias commit0='docker run -it -v "$(pwd):/project" commit0:v0'` diff --git a/README.md b/README.md index 5164f30e1..657591ffd 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,250 @@ ![zero](https://github.com/commitdev/zero/blob/master/docs/img/logo-small.png?raw=true) -This is a WIP version of our tool Zero which aims to make it quick and easy for developers to bootstrap a new environment and get to writing code. +## What is Zero -For the older, simple tool that just rendered templates, see [commitdev/zero-old][old] +Zero is an open-source developer platform CLI tool which makes it quick and easy for technical founders & developers to build quality and reliable infrastructure to launch, grow and scale high-quality SaaS applications faster and more cost-effectively. -## Press Release -Learn more about Zero's vision here: -https://docs.google.com/document/d/1YNRNgCfCHCxmIpD5ZsLYG2xCBxJLFd6CBI0DS_NFqoY/edit +## Why is Zero good for startups -## Project Board -https://app.zenhub.com/workspaces/commit-zero-5da8decc7046a60001c6db44/board?filterLogic=any&repos=203630543,247773730,257676371,258369081 +As a technical founder or the first technical hire at a startup, your sole focus is to build the logic for your application, and get it into customers’ hands as quickly and reliably as possible. Yet you immediately face multiple hurdles before even writing the first line of code. You’re forced to make many tech trade offs, leading to decision fatigue. You waste countless hours building boilerplate SaaS features not adding direct value to your customers. You spend precious time picking up unfamiliar tech, make wrong choices that result in costly refactoring or rebuilding in the future, and are unaware of tools and best practices that would speed up your product iteration. + +## Why is Zero Reliable, Scalable, Performant and Secure + +Reliability: Our infrastructure is built on multiple availability zones making our system highly available and fault tolerant. + +Scability: Our EKS infrastructure is built on top of EC2 instances, and set up with AWS's [Auto Scaling Groups][asg] is ready to scale whenever the need arises. + +Performant: Using Kubernetes leveraging containers for your services reduces overhead on virtual machines. + +Security: Properly configured access-control to resources/security groups, using secure vault systems(AWS's secret manager), and following best practices provides great security out of the box. + +___ ## Getting Started -TBD +### How to Install and Configure Zero + +There are multiple ways to install Zero: + +- Install Zero using your systems package manager. + +``` +# MacOS +brew tap commitdev/zero +brew install zero +``` + +- Install Zero by downloading the binary. + +Download the latest [Zero binary] for your systems archetecture. Unzip your downloaded package add copy the Zero binary to the desired location and add it to your system PATH. + +Zero curretnly supports: +| System | Support| Package Manager | +|---------|:-----:|:------:| +| MacOS | βœ… | `brew` | +| Linux | βœ… | n/a | +| Windows | ❌ | n/a | + +### Prerequisites + +In order to use Zero, run the `zero check` command on your system to find out which other tools / dependencies you might need to install. + +![zero-check](./docs/img/zero-check.png) + +[AWS CLI], [Kubectl], [Terraform], [jq], [Git], [Wget] + +You need to [register a new domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register.html) / [host a registered domain](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/MigratingDNS.html) you will use to access your infrastructure on [Amazon Route 53](https://aws.amazon.com/route53/). + +> We recommended you have two domains one for staging another for production. + +___ + +## Using zero to spin up your own stack + +Using Zero to spin up your infrastructure is easy and straightforward; using a few commands, you can configure and deploy your very own scalable high-performant infrastructure that is production-ready. + +A few caveats before getting started: + +- For Zero to provision resources, you will need to be authenticated with AWS [(authenticate with aws-cli)](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-methods). + + - You can also configure your aws-cli during the zero project initialization. +- It is recomended practice to [create a GitHub org](https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/creating-a-new-organization-from-scratch) where your code is going to live and grant [CircleCi Organization access](https://github.com/settings/connections/applications/78a2ba87f071c28e65bb) to your repositories for CI / CD deployment. + +- During set-up, you need to create a GitHub personal access token and a CircleCi access token; you should store your generated tokens securely. + +- For your CI build to work, you need to opt into the use of third-party orbs you can find this in your CircleCi Org Setting > Security > Allow Uncertified Orbs. + + +### zero init -#### Building this tool +The `zero init` command creates a new project and outputs an infrastructure configuration file with user input prompted responses into a file. -> πŸ“ `YOUR_PROJECT_NAME/zero-project.yml` + +```shell +# To create and customize a new project you run +$ zero init + +## Sample project initilization +βœ” Project Name: myapp-infra +πŸŽ‰ Initializing project +βœ” EKS + Go + React +βœ” Should the created projects be checked into github automatically? (y/n): y +βœ” What's the root of the github org to create repositories in?: github.com/myapp-org +βœ” Existing AWS Profiles +βœ” default + +Github personal access token: used for creating repositories for your project +Requires the following permissions: [repo::public_repo, admin::orgread:org] +The token can be created at https://github.com/settings/tokens +βœ” Github Personal Access Token with access to the above organization: + +CircleCI api token: used for setting up CI/CD for your project +The token can be created at https://app.circleci.com/settings/user/tokens +βœ” Circleci api key for CI/CD: +βœ” us-west-2 +βœ” Production Root Host Name (e.g. mydomain.com) - this must be the root of the chosen domain, not a subdomain.: commitzero.com +βœ” Production Frontend Host Name (e.g. app.): app. +βœ” Production Backend Host Name (e.g. api.): api. +βœ” Staging Root Host Name (e.g. mydomain-staging.com) - this must be the root of the chosen domain, not a subdomain.: commitzero-stage.com +βœ” Staging Frontend Host Name (e.g. app.): app. +βœ” Staging Backend Host Name (e.g. api.): api. +βœ” What do you want to call the zero-aws-eks-stack project?: infrastructure +βœ” What do you want to call the zero-deployable-backend project?: backend-service +βœ” What do you want to call the zero-deployable-react-frontend project?: frontend + +``` + +### zero create + +The `zero create` command renders the infrastructure modules you've configured into your project folder and pushed your code to GitHub. + +```shell +# Template the selected modules and configuration specified in zero-project.yml and push to repository. +$ cd zero-init # change your working dir to YOUR_PROJECT_NAME +$ zero create + +## Sample Output +πŸ•° Fetching Modules +πŸ“ Rendering Modules + Finished templating : backend-service/.circleci/README.md +βœ… Finished templating : backend-service/.circleci/config.yml +βœ… Finished templating : backend-service/.gitignore +... +... +βœ… Finished templating : infrastructure/terraform/modules/vpc/versions.tf +⬆ Done Rendering - committing repositories to version control. +βœ… Repository created: github.com/myapp-org/infrastructure +βœ… Repository created: github.com/myapp-org/backend-service +βœ… Repository created: github.com/myapp-org/frontend +βœ… Done - run zero apply to create any required infrastructure or execute any other remote commands to prepare your environments. + + +``` + +### zero apply + +The `zero apply` command takes the templated modules generated based on your input and spins up a scalable & performant infrastructure for you! + +```shell +$ zero apply + +# Sample Output +Choose the environments to apply. This will create infrastructure, CI pipelines, etc. +At this point, real things will be generated that may cost money! +Only a single environment may be suitable for an initial test, but for a real system we suggest setting up both staging and production environments. +βœ” Production +πŸŽ‰ Bootstrapping project zero-init. Please use the zero-project.yml file to modify the project as needed. +Cloud provider: AWS +Runtime platform: Kubernetes +Infrastructure executor: Terraform + +... +... + + +βœ… Done. +Your projects and infrastructure have been successfully created. Here are some useful links and commands to get you started: +zero-aws-eks-stack: +- Repository URL: github.com/myapp-org/infrastructure +- To see your kubernetes clusters, run: 'kubectl config get-contexts' +- To switch to a cluster, use the following commands: +- for production use: kubectl config use-context arn:aws:eks:us-west-2:123456789:cluster/myapp-infra-production-us-west-2 + +- To inspect the selected cluster, run 'kubectl get node,service,deployment,pods' +zero-deployable-react-frontend: +- Repository URL: github.com/myapp-org/frontend +- Deployment Pipeline URL: https://app.circleci.com/pipelines/github/myapp-org/frontend +- Production Landing Page: app.commitzero.com + +zero-deployable-backend: +- Repository URL: github.com/myapp-org/backend-service +- Deployment Pipeline URL: https://app.circleci.com/pipelines/github/myapp-org/backend-service +- Production API: api.commitzero.com +``` + +***Your stack is now up and running, follow the links your terminal to visit your application πŸŽ‰*** + + +## Zeros Default Stack + +![systerm-architecture](https://raw.githubusercontent.com/commitdev/zero-aws-eks-stack/master/docs/architecture-overview.svg) + +If you would like to learn more about the zero-aws-eks stack, you can read more about it [here](https://github.com/commitdev/zero-aws-eks-stack) +___ + +## Contributing to Zero + +Zero welcomes collaboration from the community; you can open new issues in our GitHub repo, Submit PRs' for bug fixes or browse through the tickets currently open to see what you can contribute too. + +### Building this tool ```shell $ git clone git@github.com:commitdev/zero.git -$ cd zero && make +$ cd zero && make build ``` -#### Running the tool locally + +### Running the tool locally To install the CLI into your GOPATH and test it, run: -``` + +```shell $ make install-go $ zero --help ``` +___ +## FAQ + +Why is my deployed application not yet accesible? +- It takes about 20 - 35 mins for your deployed application to be globally available through AWS CloudFront CDN. +___ ## Planning and Process -Documents should all be stored in the [Commit Zero Google Drive][drive] +Zero's documents are stored in the [Commit Zero Google Drive][drive] - [UX Design Components][ux] +- [Zeros Vision] +- [Project Board] +License: N/A -[drive]: https://drive.google.com/drive/u/0/folders/1_b8qqy5iN5envfWvIYPW5SNR_ektt5kJ -[ux]: https://docs.google.com/document/d/1yQ4bZ5z0slL9PpmduItEiCXYKIor0nX-nnGT3J-JOFw -[old]: https://github.com/commitdev/zero-old +[drive]: https://drive.google.com/drive/u/0/folders/1_b8qqy5iN5envfWvIYPW5SNR_ektt5kJ +[ux]: https://docs.google.com/document/d/1yQ4bZ5z0slL9PpmduItEiCXYKIor0nX-nnGT3J-JOFw +[old]: https://github.com/commitdev/zero-old +[git]: https://git-scm.com +[kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ +[terraform]:https://www.terraform.io/downloads.html +[jq]: https://github.com/stedolan/jq +[AWS CLI]: https://aws.amazon.com/cli/ +[acw]: https://aws.amazon.com/cloudwatch/ +[vpc]: https://aws.amazon.com/vpc/ +[iam]: https://aws.amazon.com/iam/ +[asg]: https://aws.amazon.com/autoscaling/ +[press-release]: https://docs.google.com/document/d/1YNRNgCfCHCxmIpD5ZsLYG2xCBxJLFd6CBI0DS_NFqoY/edit +[zero binary]: https://github.com/commitdev/zero/releases/tag/v0.0.1 +[zeros vision]: https://docs.google.com/document/d/1YNRNgCfCHCxmIpD5ZsLYG2xCBxJLFd6CBI0DS_NFqoY/edit +[project board]: [https://app.zenhub.com/workspaces/commit-zero-5da8decc7046a60001c6db44/board?filterLogic=any&repos=203630543,247773730,257676371,258369081] +[Wget]: https://stackoverflow.com/questions/33886917/how-to-install-wget-in-macos +[and more]: https://github.com/commitdev/zero-aws-eks-stack/blob/master/docs/resources.md \ No newline at end of file diff --git a/docs/img/zero-check.png b/docs/img/zero-check.png new file mode 100644 index 000000000..b965831d6 Binary files /dev/null and b/docs/img/zero-check.png differ