{"id":20556639,"url":"https://github.com/clevertech/boilerplate","last_synced_at":"2025-04-14T13:08:08.727Z","repository":{"id":28674830,"uuid":"116987201","full_name":"clevertech/boilerplate","owner":"clevertech","description":"Clevertech boilerplate for projects based on Docker, Node.js and React","archived":false,"fork":false,"pushed_at":"2023-01-25T09:09:54.000Z","size":6198,"stargazers_count":114,"open_issues_count":58,"forks_count":41,"subscribers_count":317,"default_branch":"master","last_synced_at":"2024-04-15T01:10:22.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clevertech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-10T17:11:39.000Z","updated_at":"2024-02-07T17:22:58.000Z","dependencies_parsed_at":"2023-02-14T06:16:38.314Z","dependency_job_id":null,"html_url":"https://github.com/clevertech/boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Fboilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Fboilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Fboilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clevertech%2Fboilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clevertech","download_url":"https://codeload.github.com/clevertech/boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248886316,"owners_count":21177643,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T03:31:03.142Z","updated_at":"2025-04-14T13:08:08.306Z","avatar_url":"https://github.com/clevertech.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clevertech Boilerplate\n\nClevertech provides an integrated technology stack that\n\n* 📚 Contains a huge amount of best practices already implemented for you\n* 🚀 Provides fast and powerful local application development. Including:\n  hot-reloading, local utilities (npm scripts), dev tools (linters, git hooks),\n  etc.\n* 🛠 Implements a solid workflow for building, testing and deploying applications\n* 👤 Secure and complete authentication functionality (including 2FA with either SMS or apps like Google Authenticator)\n* 🎨 Supports SASS/SCSS\n\nSome of the best practices include:\n\n* 📦 Caching dependencies for faster builds\n* 🚀 Fast track for faster deploys\n* 🔒 Properly storage of secrets outside the code\n* 💊 Healthcheck implementations\n* ✒️ Linters and code prettifiers\n* 👤 Complete auth infrastructure based on JWT\n* 🏛 Source code architecture that scales\n\nSome of the used technologies are:\n\n* [Node.js](https://nodejs.org/en/) for the backend.\n* [React.js](https://reactjs.org/) for the frontend with many other libraries\n  already integrated such as redux, react-router, redux-saga, etc.\n* [Docker](https://www.docker.com) for containers.\n* [Docker Compose](https://docs.docker.com/compose) to run containers locally\n  and during the build.\n* [Jenkins](https://jenkins.io) to test, build and deploy the application.\n* [Kubernetes](https://kubernetes.io) to orchestrate the container deployment.\n* [PostgreSQL](https://www.postgresql.org/) or [MySQL](https://www.mysql.com/)\n  (see the `create-boilerplate-app` script) as database engines.\n\nContainers offer big advantages in software development, quality assurance and\nsoftware deployment -- namely consistency, reliability and scalability. In\nparticular, scalability is implemented from the beginning, and the system is\nready to grow as the application gets traction.\n\n# Creating new applications\n\nTo create a new application based on the Boilerplate, use this command:\n\n```\nnpx github:clevertech/boilerplate#create-boilerplate-app my-new-app\n```\n\nThe application will be initalized in the directory `my-new-app`.\n\nThis script can be found in the\n[`create-boilerplate-app`](https://github.com/clevertech/boilerplate/tree/create-boilerplate-app)\nbranch. Follow the link for instructions on how to modify it.\n\n# Table of contents\n\n_generated with [DocToc](https://github.com/thlorenz/doctoc)_\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n* [Local Development](#local-development)\n  * [Local development tools](#local-development-tools)\n  * [Installation](#installation)\n  * [Setting up the environment](#setting-up-the-environment)\n  * [Running the application](#running-the-application)\n  * [Customizing Style](#customizing-style)\n  * [Tests](#tests)\n    * [Running the tests](#running-the-tests)\n    * [Creating new tests](#creating-new-tests)\n  * [Connecting to the database](#connecting-to-the-database)\n  * [Under the hood](#under-the-hood)\n* [Application Health Check](#application-health-check)\n  * [Quick health check](#quick-health-check)\n  * [Long health check](#long-health-check)\n* [Directory structure](#directory-structure)\n  * [Troubleshooting and useful Docker commands](#troubleshooting-and-useful-docker-commands)\n  * [Deploy](#deploy)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Local Development\n\n### Local development tools\n\nFirst of all, run `yarn install` in the root directory. This will install local\ndevelopment tools such as `eslint` and git precommits to keep the code formatted\nand without obvious errors.\n\n### Installation\n\nLocal prerequisites are minimal, please follow the\n[installation instructions](INSTALL.md) carefully. We support Linux and MacOS;\nWindows users can use Docker for Windows with several workarounds or use a Linux VM.\nReview your Docker Advanced settings and consider to assign more CPUs and more memory\nto the Docker process to boost performance.\n\n### Setting up the environment\n\nApplication configuration is done by using environment variables. For local\ndevelopment, inside each app directory there should be an `.env.example` file.\nSimply copy `.env.example` to `.env` and fill in your credentials as needed. The\n`.env.` file can be used to store sensitive / personal credentials without the\nrisk of checking it into source control.\n\n-By default [CleverAuth](https://github.com/clevertech/cleverauth) is enabled and some env variables are required for it. Take a look to `api/.env.example` and fill the required values.\n\n### Running the application\n\n```\n$ docker/run\n```\n\nThat's it! Your application is available at http://local.cleverbuild.biz:8080\n(api) and http://local.cleverbuild.biz:3000 (React frontend). Both api and\nfrontend support hot reloading.\n\n\u003e On first execution, Docker must download the base container images, which\n\u003e might take a while. Subsequent executions will be faster, taking advantage of\n\u003e Docker caching and Yarn caching. See [here](CACHING.md) for details about the\n\u003e caching mechanisms.\n\n`docker/run` is the local development start script. This allows for changes made\nlocally to restart the node application in the most efficient and cross-platform\nway. To configure the app restart, edit `nodemon.json`. `docker/run` uses\n`docker-compose` to start the application and is probably how you will want to\ndo most of your development.\n\n**NOTE:** Any change to `package.json` will require a full restart of the\ncontainer: you should use `CTRL+C` to stop the running Docker instance and\nrestart it to see your changes. To avoid that when doing simple changes (like\nadding a package), you can do something like:\n\n```\ndocker-compose run api yarn add $YOUR_PACKAGE$\n```\n\n### Customizing Style\n\nThe boilerplate supports styling with SASS/SCSS. Just edit `main.scss` on `frontend/src/styles` and the boilerplate will convert it to css on-the-fly so you can take full advantage of all of SASS's features.\n\n### Tests\n\n#### Running the tests\n\n```\n$ docker/test\n```\n\n#### Creating new tests\n\n**Unit tests**\n\nJust write regular tests using `jest`. Use `describe()` and `it()` to write new\ntests and test suites.\n\n**End 2 end tests**\n\nEnd to end tests are implemented using\n[TestCafe](https://devexpress.github.io/testcafe/). You can find an example in\n`e2e`. These tests need to be run having the containers up.\n\n```\nyarn run e2e\n```\n\n### Connecting to the database\n\nYou'll find the password in the `docker-compose.yml` file.\n\n_From the command line_\n\nWith the containers started just do:\n\n```\nyarn run db-client\n```\n\n_Using Adminer_\n\nJust go to `http://127.0.0.1:8081/` and fill the connection information based on\nwhat you'll find in `docker-compose.yml`.\n\n### Under the hood\n\n[How it works](docker/README.md).\n\n## Application Health Check\n\nEach application should expose two health checks.\n\n### Quick health check\n\nThe quick health checks is called by Kubernetes to assess the\n[Liveness and Readiness](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)\nof an application; it is called approximately every 10-30 seconds, so it can not\ninvolve any computation or resource access (database, cache, etc.) to not stress\nthe infrastructure. For a web application, an endpoint returning HTTP 200 is\nusually the right choice.\n\nURL: `/healthz`\n\n### Long health check\n\nThe long health checks is called by an external service to assess the status of\nthe entire application stack. It is called approximately every 1 minute, so it\ncan involve computation and light access to external resources. The long health\ncheck should verify the liveness of every dependent service and:\n\n* Return HTTP 200 if everything is good.\n* Return HTTP 500 and a human-readable error message if something is wrong.\n\nExamples of controlled services:\n\n* Simple query to assess database liveness and connectivity (`SELECT 1;`)\n* Simple query to assess Redis connectivity\n* Simple API call to assess external REST API liveness and connectivity\n\nA module should also check for a consistent internal state. For example: a\nemail-sending worker should check for the sending queue to be less than a\ncertain thresholds; a workerd consuming events in a queue should check for queue\nsize, etc.\n\nThe long health check should be authenticated to avoid a potential DoS attack.\nThe secret for the long health check is passed as an environment variable to the\nprocess (`HEALTH_CHECK_SECRET`).\n\nURL: `/healthz/long/${process.env.HEALTH_CHECK_SECRET}`\n\n## Directory structure\n\nThis project is setup to have multiple services in the same repository, as such\nthe structure of this is quite important. Each directory of this project is\nintended to be for a different service and as such, those child folders should\ncontain all necessary components to build that service entirely.\n\nIt is important that each new service has a `Dockerfile`.\n\n```\nproject\n├─ docker-compose.yml\n├─ README.md\n├─ INSTALL.md\n├─ api\n│  ├─ Dockerfile\n|  ├─ package.json\n│  └─ src\n│     ├─ file1.js\n│     └─ file2.js\n└─ frontend\n   ├─ Dockerfile\n   ├─ package.json\n   └─ src\n      ├─ file1.js\n      └─ file2.js\n```\n\n### Troubleshooting and useful Docker commands\n\n[Common issues](TROUBLESHOOTING.md) that developers may encounter when executing\nthis project and useful Docker commands.\n\n### Deploy\n\nBranches `development`, `staging` and `master` are deployed after build to their\nserver environments.\n\nThe deploy uses a `fast-path` mechanism. When a given application version is\ntested on the development site, the same container image is deployed on the\nstaging/production site, avoiding to repeat the build and testing process when\npromoting a new version to staging/production. This allows to put a new version\non production in 30 seconds and to avoid build inconsistencies.\n\nThe mechanism is triggered when a build is started for a branch which is\nidentical to another branch that has already been built and deployed. So, for\nexample, when you merge `development` to `staging` (without code modifications)\nthe build phase is skipped, and the existing image is deployed. To take\nadvantage of the fast path, do not merge `development` to `staging` while\ndevelopment is still building: it's faster and safer to wait for development\nbuild completion before merging.\n\nAs also Pull Requests are built, this mechanism works in some cases also for\nPRs. For example, if you merge a **rebased** PR to `development`, the fast path\nis used.\n\nImplementation is in `docker/fast_track` script.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Fboilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclevertech%2Fboilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclevertech%2Fboilerplate/lists"}