From 57dfa69e212e950b11d20f1fee35fa255a849ec5 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Mon, 8 Mar 2021 22:53:37 -0500 Subject: [PATCH 01/10] Update and reorganize CONTRIBUTING, including splitting Code and Running Server into two sections. Better differentiate Docker Mode from Manual Mode --- CONTRIBUTING.md | 228 ++++++++++++++++++++++++++---------------------- 1 file changed, 126 insertions(+), 102 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f4271a1a7b..94087635b3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,44 +2,45 @@ Hello. :wave: -Welcome to Chapter, the newest project by freeCodeCamp. We are glad to see your interest in this project. +Welcome to **_Chapter_** , the newest project by [freeCodeCamp](https://www.freecodecamp.org). We strictly enforce our ["Code of Conduct"](https://www.freecodecamp.org/code-of-conduct). Please take a moment to read it. It's only 196 words long. -You should [join our chat](https://chat.freecodecamp.org/channel/chapter) to get connected with the Chapter project's development team. +You should [join our chat](https://chat.freecodecamp.org/channel/chapter) to get connected with this project's development team. -## Contribute code +## Contributing Code -If you are willing to contribute code to this project then you should follow the below steps: +If you are ready to contribute code, then start by follow these steps. -
Step 1: Fork the repository on GitHub +
Step 1 - Fork the repository on GitHub -['Forking'](https://help.github.com/articles/about-forks/) is a step where you get your own copy of Chapter's repository (a.k.a repo) on GitHub. +['Forking'](https://help.github.com/articles/about-forks/) is a step where you get your own copy of **_Chapter's_** repository (a.k.a repo) on GitHub. -This is essential as it allows you to work on your own copy of Chapter. It allows you to request changes to be pulled into the Chapter's repository from your fork via a pull request. +This is essential as it allows you to work on your own copy of **_Chapter_**. It allows you to request changes to be pulled into the **_Chapter's_** repository from your fork via a pull request. -Follow these steps to fork the `https://github.com/freeCodeCamp/chapter` repository: -1. Go to the Chapter repository on GitHub: . -2. Click the "Fork" Button in the upper right-hand corner of the interface ([Need help?](https://help.github.com/articles/fork-a-repo/)). -3. After the repository has been forked, you will be taken to your copy of the Chapter repository at `https://github.com/YOUR_USER_NAME/chapter`. +Follow these steps to fork the repository: +1. Go to the [Chapter repository on GitHub](https://github.com/freeCodeCamp/chapter). +2. Click the "Fork" Button in the upper right-hand corner of the interface [Need help?](https://help.github.com/articles/fork-a-repo/). +3. After the repository has been forked, you will be taken to your copy of the **_Chapter_** repository at `https://github.com/YOUR_USER_NAME/chapter`. ![an image illustrating the fork button](docs/assets/how-to-fork.png)
-
Step 2: Preparing the development environment + +
Step 2 - Preparing the development environment Install [Git](https://git-scm.com/) and a code editor of your choice. We recommend using [VS Code](https://code.visualstudio.com/). -Clone your copy of Chapter. ['Cloning'](https://help.github.com/articles/cloning-a-repository/) is where you download a copy of the repository from a `remote` location to your local machine. Run these commands on your local machine to clone the repository: +Clone your copy of **_Chapter_**. ['Cloning'](https://help.github.com/articles/cloning-a-repository/) is where you download a copy of the repository from a `remote` location to your local machine. Run these commands on your local machine to clone the repository: -1. Open a Terminal in a directory where you would like the Chapter project to reside. +1. Open a Terminal in a directory where you would like the **_Chapter_** project to reside. -2. Clone your fork of Chapter, make sure you replace `YOUR_USER_NAME` with your GitHub username: +2. Clone your fork of **_Chapter_**, make sure you replace `YOUR_USER_NAME` with your GitHub username: ```sh git clone https://github.com/YOUR_USER_NAME/Chapter.git ``` -This will download the entire Chapter repository to your directory. +This will download the entire **_Chapter_** repository to your directory. Now that you have downloaded a copy of your fork, you will need to set up an `upstream`. The main repository at `https://github.com/freeCodeCamp/chapter` is often referred to as the `upstream` repository. Your fork at `https://github.com/YOUR_USER_NAME/chapter` is often referred to as the `origin` repository. @@ -73,71 +74,16 @@ You need a reference from your local copy to the `upstream` repository in additi
-
Step 3: Running Chapter locally - -You will need Node.js for your operating system. So download and install Node.js from the [official Node.js website](https://nodejs.org/en/download/). - -Ensure you are installing Node.js 13 or greater and npm 6 or greater by using: -``` -node --version -v14.13.1 - -npm --version -6.14.8 -``` - -Then install the dependencies using: -``` -npx recursive-install -``` - -There are two approaches to running Chapter locally. First by using Docker and second by setting up client-server, db, api-server all by yourself. Let's see the Docker method first then we'll see a more hands-on method. - -**First method: using Docker** +
Step 3 - Decide Whether to Run the Application Now, or Later +It's possible to contribute simple changes, like to README.md, without running the application. However, for many situations you will need to get the application running to view pages, see your code in action, and test changes. -See the [Docker installation "Supported platforms"](https://docs.docker.com/install/#supported-platforms) section and follow the instructions to download & install Docker Desktop for your operating system (or Docker CE for Linux). - -You can find more resources on Docker here: -- [Docker: What and Why](https://stackoverflow.com/questions/28089344/docker-what-is-it-and-what-is-the-purpose) -- [Docker Lessons on KataCoda](https://www.katacoda.com/learn?q=docker) -- [Play with Docker Classroom](https://training.play-with-docker.com/) - - -Ensure that Docker Desktop is up and running, then run the following command: -``` -docker-compose up -``` - -Wait for the logs to show "server started on port 8000", then navigate to `localhost:8000` to view the app. - -The server will automatically restart anytime you save a `.ts` or `.js` file within the `server/` directory. - -You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` +If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **Running the Application** section, below. Then, return here and continue to the next step of this section. -Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. - -**Note for existing contributors:** If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. And then run `docker-compose up` to start the container's services. - -**Second method: manually managing the client-server, db, api-server** - -This is a lot lighter setup, but you need to provide your own Postgres DB. If you don't want to run one locally you can get it as a service on [ElephantSQL](https://www.elephantsql.com/). - -[Download and Install PostgreSQL](https://www.postgresql.org/download/). Then create a database, add the DB name and credentials to `.env`. If using remote database change `DB_URL` in `.env` to the URL provided by your remote database provider. - -Make sure to set `IS_DOCKER=` in `.env` to blank. Then run the below command to start the api-server and client-server: - -``` -npm run both -``` - -Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`.
-
Step 4: Making changes to Chapter codebase and Testing code :fire: - -> **Note: Always follow the below steps before you start coding or working on an issue.** +
Step 4 - Making Changes and Testing the Code :fire: -You are now almost ready to make changes to files but before that you should **always** follow these steps: +You are almost ready to make changes to files, but before that you should **always** follow these steps: 1. Validate that you are on the `master` branch @@ -227,21 +173,9 @@ You are now almost ready to make changes to files but before that you should **a 5. Test your code **Always!** -If you have done manual server setup that is without Docker then run tests using: -``` -npm run test -``` - -If you used Docker then suffix the command with `docker-compose exec`. Something like this: - -``` -NODE_ENV=test docker-compose exec app npm run test -``` - -You can run tests in watch mode by running: -``` -npm run test:watch -``` +- If you started the application using the _Docker Mode_, then tests are run using `NODE_ENV=test docker-compose exec app npm run test` OR if you want to use the "watch" mode run `NODE_ENV=test docker-compose exec app npm run test:watch` +- If you started the application using the _Manual Mode_ (without Docker), then tests are run using +`npm run test` OR if you want to use the "watch" mode run `npm run test:watch` 6. Stage the changes and make a commit @@ -306,7 +240,7 @@ npm run test:watch
Step 5: Proposing a Pull Request (PR) -#### How to prepare a good Pull Request title: +#### How to Prepare a Good Pull Request Title When opening a Pull Request(PR), use the following scope table to decide what to title your PR in the following format: @@ -327,11 +261,11 @@ An example is `feat(client): night mode`. ![an image showing Compare & pull request prompt on GitHub](docs/assets/pull-request-prompt.png) -2. By default, all pull requests should be against the Chapter main repo, `master` branch. +2. By default, all pull requests should be against the **_Chapter_** main repo, `master` branch. ![ an image showing the comparison of forks when making a pull request](docs/assets/comparing-forks-for-pull-request.png) -3. Submit the pull request from your branch to Chapter's `master` branch. +3. Submit the pull request from your branch to **_Chapter's_** `master` branch. 4. In the body of your PR include a more detailed summary of the changes you made and why. @@ -347,17 +281,96 @@ An example is `feat(client): night mode`. You have successfully created a PR. Congratulations! :tada:
+## Starting / Running the Application + +
Step 1 - Install Node and Run npx + +You will need Node.js installed on your host operating system. + +Download and install Node.js from the [official Node.js website](https://nodejs.org/en/download/). + +Now check that you have running: +* Node.js 14 or greater - `node --version` and the output should be like **v14**.16.0 +* npm 6 or greater - `npm --version` and the output should be like **6**.14.11 + +Run `npx recursive-install` and this will install all of the necessary dependencies. + +
+ +
Step 2 - Run the App Using Docker Mode OR Manual Mode +There are two approaches to running the **_Chapter_** application. + +Based on your experience or preference, decide between the two options: +* _Docker Mode_: typically easier if you just want to start the application for the first time or don't want to run a local Postgres database on your host computer. It will take longer to "boot up" the container than manual-mode and can be slow to reload some types of code changes. +* _Manual Mode_: more of a "hands-on" method, is more lightweight in that it's faster to "boot" and faster to refresh for some code changes, requires more knowledge of running Postgres and configuring localhost services to play nice with the code. + +### Docker Mode + +Follow the [Get Docker](https://docs.docker.com/get-docker/) instructions to download & install the required tools for your host operating system: +* Docker Desktop (Windows and Mac) +* Docker Engine (Linux) and Docker Compose + +You can find more resources on Docker here: +* [Docker: What and Why](https://stackoverflow.com/questions/28089344/docker-what-is-it-and-what-is-the-purpose) +* [Docker Lessons on KataCoda](https://www.katacoda.com/learn?q=docker) +* [Play with Docker Classroom](https://training.play-with-docker.com/) + +Ensure the Docker tools are installed: +* For Windows & Mac, check Docker Desktop +* For Linux +** Docker Engine using `docker --version` and it should output something like _Docker version 19.03.13..._ +** Docker Compose using `docker-compose --version` and it should output something like _docker-compose version 1.28.5..._ + +Run Docker Compose using `docker-compose up` and wait (this could take many minutes) for the logs show +> db_1 | ... LOG: database system is ready to accept connections +and +> client_1 | ready - started server on http://localhost:3000 +and +> app_1 | Listening on http://localhost:5000/graphql + +The server will automatically restart anytime you save a `.ts` or `.js` file within the `server/` directory. + +You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` + +Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. + +#### Note for Existing Contributors +If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. And then run `docker-compose up` to start the container's services. + +### Manual Mode + +With this method you will manually managing the client-server, Postgres database, and API server. + +This is a much lighter development footprint than Docker, but you need to run your own local Postgres DB. If you don't want to run Postgres locally, then you can use a service like [ElephantSQL](https://www.elephantsql.com/). + +[Download and Install PostgreSQL](https://www.postgresql.org/download/). Then create a database, add the DB name and credentials to `.env`. If using remote database change `DB_URL` in `.env` to the URL provided by your remote database provider. + +Make sure to set `IS_DOCKER=` in `.env` to blank. Then, run `npm run both` to start the api-server and client-server: + +Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. +
+ +
Step 3 - View the Running Application +Once the app has started you should be able to pull up these URLs in your web browser: + +* Main client website - `http//:localhost:3000` +* GraphQL Playground - `http://localhost:5000/graphql` + +
+ ## Frequently Asked Questions -### What do we need help with right now? +
What do we need help with right now? We are in the very early stages of development on this new application. We value your insight and expertise. In order to prevent duplicate issues, please search through our existing issues to see if there is one for which you would like to provide feedback. We are currently trying to consolidate many of the issues based on topics like documentation, user interface, API endpoints, and architecture. Please [join our chat](https://chat.freecodecamp.org/channel/chapter) to stay in the loop. +
-### I found a typo. Should I report an issue before I can make a pull request? +
I found a typo. Should I report an issue before I can make a pull request? For typos and other wording changes, you can directly open pull requests without first creating an issue. Issues are more for discussing larger problems associated with code or structural aspects of the application. - -### I am new to GitHub and Open Source, where should I start? +
+ +
I am new to GitHub and Open Source, where should I start? Read our [How to Contribute to Open Source Guide](https://github.com/freeCodeCamp/how-to-contribute-to-open-source). @@ -378,20 +391,32 @@ When in doubt, you can reach out to current project lead(s): You are a champion :). +
+ # Server-side Technical Documentation ## API Specification We use [GraphQL](https://graphql.org/) to define the API structure of the application. -See the "Docs" and "Schema" tabs on the right side of the [GraphQL Playground](https://chapter-server.herokuapp.com/graphql), or locally at /graphql, for full API documentation. +See the "Docs" and "Schema" tabs on the right side of the [GraphQL Playground](https://chapter-server.herokuapp.com/graphql), or locally at http://localhost:5000/graphql for full API documentation. ## Database -for any problems ping [@Zeko369 on github](https://github.com/Zeko369) or [chat](https://chat.freecodecamp.org/channel/chapter) +For any problems ping [@Zeko369 on github](https://github.com/Zeko369) or [chat](https://chat.freecodecamp.org/channel/chapter) + +If using **Docker Mode**: +* The Docker database Postgres container will be exposed to the host computer on localhost port 54320. Thus, avoding potential conflicts on port 543 in the case your host computer already runs Postgres. +* You don't have to run `docker-compose exec...` commands to "talk" to the Postgres container. Rather, use the Postgres client `psql -h localhost -p 54320 -U postgres` where your .env file defines the Postgres username and password. +* Database tools like [Postico](https://eggerapps.at/postico/) or [Table Plus](https://tableplus.com/) can access + +If using **Manual Mode** +* The Postgres port will be as you configured it, likely localhost port 543 +* Use the Postgres client `psql -h localhost -p 543 -U postgres` where your .env file defines the Postgres username and password +
-Expand to view a diagram illustrating the proposed schema for Chapter. +Expand to view a diagram illustrating the database schema.
![a diagram illustrating the proposed schema for Chapter](docs/data/schema.png) @@ -400,7 +425,6 @@ for any problems ping [@Zeko369 on github](https://github.com/Zeko369) or [chat] We're using Postgres for our database and TypeORM for our ORM (mapping database tables to js objects). Here are a few examples on how to use our TypeORM setup. -To make it since the port from docker `postgres` service is exposed to the host (54320, not to mess with local `postgres` if you're running one) you don't have to run `docker-compose exec...`, and can just run db commands from the host. This also makes it a lot easier to access the db from the outside if you're not running a local db on the system to for example open it in [Postico](https://eggerapps.at/postico/) / [Table Plus](https://tableplus.com/). Our DB commands closely mirror their rails counterparts (there isn't anything quite similar to ActiveRecord and RailsCLI in node yet, so till then #rails 🚋 ) `yarn db:generate NAME` -> `rake db:generate NAME`, note that this command checks for the diff between models and db, unlike rails where you need to specify the migration by hand From 166bc4ad77f0646c1143599fad6633be3efd97dc Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Mon, 8 Mar 2021 23:31:09 -0500 Subject: [PATCH 02/10] Rework the Database section of CONTRIBUTING.md --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 94087635b3..d3910e6bcc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ We strictly enforce our ["Code of Conduct"](https://www.freecodecamp.org/code-of You should [join our chat](https://chat.freecodecamp.org/channel/chapter) to get connected with this project's development team. -## Contributing Code +# Contributing Code If you are ready to contribute code, then start by follow these steps. @@ -240,8 +240,6 @@ You are almost ready to make changes to files, but before that you should **alwa
Step 5: Proposing a Pull Request (PR) -#### How to Prepare a Good Pull Request Title - When opening a Pull Request(PR), use the following scope table to decide what to title your PR in the following format: `fix/feat/chore/refactor/docs/perf (scope): PR Title` @@ -255,8 +253,6 @@ An example is `feat(client): night mode`. | `client` | For Pull Requests making changes to client platform logic or user interface | | `docs` | For Pull Requests making changes to the project's documentation | -#### Proposing a Pull Request (PR) - 1. Once the edits have been committed & pushed, you will be prompted to create a pull request on your fork's GitHub Page. Click on `Compare and Pull Request`. ![an image showing Compare & pull request prompt on GitHub](docs/assets/pull-request-prompt.png) @@ -281,7 +277,8 @@ An example is `feat(client): night mode`. You have successfully created a PR. Congratulations! :tada:
-## Starting / Running the Application +# Starting / Running the Application +Prerequisite: steps 1 and 2 of the **Contributing Code** section above must be done before following this section's steps.
Step 1 - Install Node and Run npx @@ -304,7 +301,7 @@ Based on your experience or preference, decide between the two options: * _Docker Mode_: typically easier if you just want to start the application for the first time or don't want to run a local Postgres database on your host computer. It will take longer to "boot up" the container than manual-mode and can be slow to reload some types of code changes. * _Manual Mode_: more of a "hands-on" method, is more lightweight in that it's faster to "boot" and faster to refresh for some code changes, requires more knowledge of running Postgres and configuring localhost services to play nice with the code. -### Docker Mode +## Docker Mode Follow the [Get Docker](https://docs.docker.com/get-docker/) instructions to download & install the required tools for your host operating system: * Docker Desktop (Windows and Mac) @@ -334,14 +331,16 @@ You can run any command within the container by prefixing it with `docker-compos Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. -#### Note for Existing Contributors +**(Note for Existing Contributors)** If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. And then run `docker-compose up` to start the container's services. -### Manual Mode +## Manual Mode With this method you will manually managing the client-server, Postgres database, and API server. -This is a much lighter development footprint than Docker, but you need to run your own local Postgres DB. If you don't want to run Postgres locally, then you can use a service like [ElephantSQL](https://www.elephantsql.com/). +This is a much lighter development footprint than Docker, but you need to run your own local Postgres DB. + +If you don't want to run Postgres locally, then you can use a service like [ElephantSQL](https://www.elephantsql.com/). [Download and Install PostgreSQL](https://www.postgresql.org/download/). Then create a database, add the DB name and credentials to `.env`. If using remote database change `DB_URL` in `.env` to the URL provided by your remote database provider. @@ -358,7 +357,7 @@ Once the app has started you should be able to pull up these URLs in your web br
-## Frequently Asked Questions +# Frequently Asked Questions
What do we need help with right now? @@ -403,18 +402,25 @@ See the "Docs" and "Schema" tabs on the right side of the [GraphQL Playground](h ## Database -For any problems ping [@Zeko369 on github](https://github.com/Zeko369) or [chat](https://chat.freecodecamp.org/channel/chapter) +We're using [Postgres](https://www.postgresql.org/) for our database and [TypeORM](https://typeorm.io/) for our ORM (mapping database tables to js objects). -If using **Docker Mode**: -* The Docker database Postgres container will be exposed to the host computer on localhost port 54320. Thus, avoding potential conflicts on port 543 in the case your host computer already runs Postgres. -* You don't have to run `docker-compose exec...` commands to "talk" to the Postgres container. Rather, use the Postgres client `psql -h localhost -p 54320 -U postgres` where your .env file defines the Postgres username and password. -* Database tools like [Postico](https://eggerapps.at/postico/) or [Table Plus](https://tableplus.com/) can access +### Username and Password +* These are defined in your _.env_ configuration file in the project's root directory. +* The .env is unique to your copy and should not be committed to any repository or branch. +* For security, it's ideal to change the username and password. However, if you don't change them, the default username and password will be as they are set in .env -If using **Manual Mode** -* The Postgres port will be as you configured it, likely localhost port 543 -* Use the Postgres client `psql -h localhost -p 543 -U postgres` where your .env file defines the Postgres username and password +### Host and Port +* In **Docker Mode**, the Docker database container will be exposed to the host computer on Host: _localhost_ and Port: _54320_. Thus, avoiding potential port conflicts in the case your computer is running Postgres locally for other projects. +* In **Manual Mode**, the Postgres port will be as you configured it, the default being Host: _localhost_ and Port: _543_ +* If you're using a remote Postgres server, like [ElephantSQL](https://www.elephantsql.com/), then the Host and Port will be provided by the service. You'll also need to update the `DB_URL` value in your _.env_ file. +### Admin Tools +* [pgAdmin](https://www.pgadmin.org/), [Postico](https://eggerapps.at/postico/) or [Table Plus](https://tableplus.com/), can use the *** Host and Port** values above, based on your mode. +* psql Client + * In **Docker Mode**, `psql -h localhost -p 54320 -U postgres`. You don't have to run `docker-compose exec...` commands to "talk" to the Postgres container. + * In **Manual Mode**, `psql -h localhost -p 543 -U postgres` +### Schema
Expand to view a diagram illustrating the database schema.
@@ -423,16 +429,16 @@ If using **Manual Mode** > created with [DBeaver.io](https://dbeaver.com/docs/wiki/ER-Diagrams/)
-We're using Postgres for our database and TypeORM for our ORM (mapping database tables to js objects). Here are a few examples on how to use our TypeORM setup. +### Using TypeORM and Yarn -Our DB commands closely mirror their rails counterparts (there isn't anything quite similar to ActiveRecord and RailsCLI in node yet, so till then #rails 🚋 ) +Our DB commands closely mirror their Rails counterparts (there isn't anything quite similar to ActiveRecord and RailsCLI in node yet, so till then #rails 🚋 ) `yarn db:generate NAME` -> `rake db:generate NAME`, note that this command checks for the diff between models and db, unlike rails where you need to specify the migration by hand `yarn db:migrate` -> `rake db:migrate` `yarn db:seed` -> `rake db:seed` `yarn db:reset` -> `rake db:reset` -### Seed Database +#### Seeding the Database `yarn db:seed` @@ -440,7 +446,7 @@ Development is easier with a database full of example entities. The process of c Use `yarn db:seed` to create these example entities. But first (if the you're just starting) you need to migrate the DB (setup tables). For that you can use `yarn db:reset` which will drop the current db (clear), migrate it (add structure) and then seed it (add data) -### Create a New Model / Entity +#### Creating a New Model / Entity `npm run typeorm entity:create -- --name=ModelName` @@ -450,7 +456,7 @@ To keep everything DRY, add `extends BaseModel` to the class and import it from You could also run `npx typeorm` since here you're not actually loading any ts files, but because regular `npx typeorm` runs inside of node it import from `.ts` files, so we run it with `ts-node` and our custom server config (check package.json) -### Create a Migration +#### Creating a Migration After you created a new model or updated an existing one, you need to generate a migration for those changes. To do so run: @@ -460,7 +466,7 @@ Since this runs a compare agains the current db schema, you need to have the DB After that, check the generated SQL in `db/migrations/date-MigrationName.ts` -### Running migrations and checking if migrations were run +#### Running Migrations and Checking They Were Run You can manualy run them by doing `yarn db:migrate` @@ -476,3 +482,8 @@ it should ouput something like ... [X] MigrationName1575633316367 ``` + +### Troubleshooting + +For any problems ping [@Zeko369 on github](https://github.com/Zeko369) or [chat](https://chat.freecodecamp.org/channel/chapter). + From e12b0e7a72675eedb27c619836f8fb8476d7d45a Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Mon, 8 Mar 2021 23:34:46 -0500 Subject: [PATCH 03/10] Attempt to add internal page anchor section links to CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d3910e6bcc..5ac475c3b8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,7 +77,7 @@ You need a reference from your local copy to the `upstream` repository in additi
Step 3 - Decide Whether to Run the Application Now, or Later It's possible to contribute simple changes, like to README.md, without running the application. However, for many situations you will need to get the application running to view pages, see your code in action, and test changes. -If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **Running the Application** section, below. Then, return here and continue to the next step of this section. +If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **[Running the Application](#starting--running-the-application)** section, below. Then, return here and continue to the next step of this section.
@@ -278,7 +278,7 @@ You have successfully created a PR. Congratulations! :tada:
# Starting / Running the Application -Prerequisite: steps 1 and 2 of the **Contributing Code** section above must be done before following this section's steps. +Prerequisite: steps 1 and 2 of the [**Contributing Code**](#contributing-code**) section above must be done before following this section's steps.
Step 1 - Install Node and Run npx From ae0cbb9047a91a3a67b9d8ab02d69e0d4b8160e1 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Mon, 8 Mar 2021 23:36:26 -0500 Subject: [PATCH 04/10] Fix bad anchor link in CONTRIBUTING.md --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ac475c3b8..82178fb0ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,7 +77,7 @@ You need a reference from your local copy to the `upstream` repository in additi
Step 3 - Decide Whether to Run the Application Now, or Later It's possible to contribute simple changes, like to README.md, without running the application. However, for many situations you will need to get the application running to view pages, see your code in action, and test changes. -If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **[Running the Application](#starting--running-the-application)** section, below. Then, return here and continue to the next step of this section. +If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **[Running the Application](#running-the-application)** section, below. Then, return here and continue to the next step of this section.
@@ -277,8 +277,8 @@ An example is `feat(client): night mode`. You have successfully created a PR. Congratulations! :tada:
-# Starting / Running the Application -Prerequisite: steps 1 and 2 of the [**Contributing Code**](#contributing-code**) section above must be done before following this section's steps. +# Running the Application +Prerequisite: steps 1 and 2 of the [**Contributing Code**](#contributing-code) section above must be done before following this section's steps.
Step 1 - Install Node and Run npx From 5b21007ea3dd65c6102b19f86c3f4b8b0ab922f9 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Mon, 8 Mar 2021 23:44:22 -0500 Subject: [PATCH 05/10] Rework the API Specification in CONTRIBUTING.md --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 82178fb0ca..6155bf2864 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -398,7 +398,9 @@ You are a champion :). We use [GraphQL](https://graphql.org/) to define the API structure of the application. -See the "Docs" and "Schema" tabs on the right side of the [GraphQL Playground](https://chapter-server.herokuapp.com/graphql), or locally at http://localhost:5000/graphql for full API documentation. +The GraphQL Playground has "Docs" and "Schema" tabs on the right side of the page. You can see them: +* If you are already [**Running the Application**](#running-the-application) at http://localhost:5000/graphql +* If you don't have a running ap by visiting [GraphQL Playground](https://chapter-server.herokuapp.com/graphql). (Note, this is a free-tier of Heroku. Hit refresh every minute or two if the page fails to load and it should eventually "wake" the server.) ## Database From b2660d44662767aeef082c1bbd3f245a53f03f59 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Tue, 9 Mar 2021 00:21:45 -0500 Subject: [PATCH 06/10] Rework the database seeding / initialization section of CONTRIBUTING.md --- CONTRIBUTING.md | 49 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6155bf2864..8b7c4c645a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,9 +75,10 @@ You need a reference from your local copy to the `upstream` repository in additi
Step 3 - Decide Whether to Run the Application Now, or Later + It's possible to contribute simple changes, like to README.md, without running the application. However, for many situations you will need to get the application running to view pages, see your code in action, and test changes. -If you want to proceed immeditely with running the client, database, and server, then follow the steps in the **[Running the Application](#running-the-application)** section, below. Then, return here and continue to the next step of this section. +If you want to proceed immeditely with running the client, database, and server, then follow the steps in the [**Running the Application**](#running-the-application) section, below. Then, return here and continue to the next step of this section.
@@ -278,7 +279,7 @@ You have successfully created a PR. Congratulations! :tada:
# Running the Application -Prerequisite: steps 1 and 2 of the [**Contributing Code**](#contributing-code) section above must be done before following this section's steps. +Prerequisite: Follow steps 1 and 2 of the [**Contributing Code**](#contributing-code) section, above, before continuing to the next step in this section.
Step 1 - Install Node and Run npx @@ -286,18 +287,21 @@ You will need Node.js installed on your host operating system. Download and install Node.js from the [official Node.js website](https://nodejs.org/en/download/). -Now check that you have running: +Now check that you have: + * Node.js 14 or greater - `node --version` and the output should be like **v14**.16.0 * npm 6 or greater - `npm --version` and the output should be like **6**.14.11 -Run `npx recursive-install` and this will install all of the necessary dependencies. +Run `npx recursive-install` to install all of the necessary dependencies.
Step 2 - Run the App Using Docker Mode OR Manual Mode + There are two approaches to running the **_Chapter_** application. Based on your experience or preference, decide between the two options: + * _Docker Mode_: typically easier if you just want to start the application for the first time or don't want to run a local Postgres database on your host computer. It will take longer to "boot up" the container than manual-mode and can be slow to reload some types of code changes. * _Manual Mode_: more of a "hands-on" method, is more lightweight in that it's faster to "boot" and faster to refresh for some code changes, requires more knowledge of running Postgres and configuring localhost services to play nice with the code. @@ -318,21 +322,23 @@ Ensure the Docker tools are installed: ** Docker Engine using `docker --version` and it should output something like _Docker version 19.03.13..._ ** Docker Compose using `docker-compose --version` and it should output something like _docker-compose version 1.28.5..._ -Run Docker Compose using `docker-compose up` and wait (this could take many minutes) for the logs show +Make sure `IS_DOCKER=TRUE` is set in the `.env` file in your copy's root directory. + +Run Docker Compose using `docker-compose up` and wait (this could take many minutes) for the logs show: > db_1 | ... LOG: database system is ready to accept connections -and +> ... > client_1 | ready - started server on http://localhost:3000 -and +> ... > app_1 | Listening on http://localhost:5000/graphql The server will automatically restart anytime you save a `.ts` or `.js` file within the `server/` directory. You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` -Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. +Initially, the database will be empty. Now, to seed it with sample data, run `yarn db:reset`. **(Note for Existing Contributors)** -If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. And then run `docker-compose up` to start the container's services. +If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. Then, run `docker-compose up` to start the container's services. ## Manual Mode @@ -344,12 +350,17 @@ If you don't want to run Postgres locally, then you can use a service like [Elep [Download and Install PostgreSQL](https://www.postgresql.org/download/). Then create a database, add the DB name and credentials to `.env`. If using remote database change `DB_URL` in `.env` to the URL provided by your remote database provider. -Make sure to set `IS_DOCKER=` in `.env` to blank. Then, run `npm run both` to start the api-server and client-server: +Make sure to set `IS_DOCKER=` to blank in the `.env` file in your project's root directory. + +Run `npm run both` to start the api-server and client-server: -Initially the DB will be empty. Now, to seed it with sample data, run `yarn db:reset`. +
Step 3 - Prepare the Database for Development +Initially, the database may be empty or need to be recreated. + +See the [Initializing the Database](#initializing-the-database) section, below, before continuing to the next step in this section.
-
Step 3 - View the Running Application +
Step 4 - View the Running Application Once the app has started you should be able to pull up these URLs in your web browser: * Main client website - `http//:localhost:3000` @@ -440,13 +451,19 @@ Our DB commands closely mirror their Rails counterparts (there isn't anything qu `yarn db:seed` -> `rake db:seed` `yarn db:reset` -> `rake db:reset` -#### Seeding the Database +#### Initializing the Database -`yarn db:seed` +If you're starting the application for the first time, you need to: +* (optionally) drop the database - to delete all the structure and data +* migrate the database - to structure by setup tables based on the schema +* seed the database - development is easier with a database full of example entities. The process of creating example entities in the database is called seeding -Development is easier with a database full of example entities. The process of creating example entities in the database is called seeding. +The `yarn db:reset` command will do all three tasks: drop, migrate, and seed. -Use `yarn db:seed` to create these example entities. But first (if the you're just starting) you need to migrate the DB (setup tables). For that you can use `yarn db:reset` which will drop the current db (clear), migrate it (add structure) and then seed it (add data) +If you prefer to run any or all of the steps manually, they are: +* `yarn db:drop` +* `yarn db:migrate` +* `yarn db:seed` #### Creating a New Model / Entity From 58bb261e58a2853354d7244285daecd42c228a7f Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Tue, 9 Mar 2021 00:30:28 -0500 Subject: [PATCH 07/10] Fix missing section tag in CONTRIBUTING.md and further tweak the Database docs --- CONTRIBUTING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b7c4c645a..2103e79c70 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -335,8 +335,6 @@ The server will automatically restart anytime you save a `.ts` or `.js` file wit You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` -Initially, the database will be empty. Now, to seed it with sample data, run `yarn db:reset`. - **(Note for Existing Contributors)** If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. Then, run `docker-compose up` to start the container's services. @@ -353,9 +351,10 @@ If you don't want to run Postgres locally, then you can use a service like [Elep Make sure to set `IS_DOCKER=` to blank in the `.env` file in your project's root directory. Run `npm run both` to start the api-server and client-server: +
Step 3 - Prepare the Database for Development -Initially, the database may be empty or need to be recreated. +The database may be empty or need to be recreated to get any structureal changes made by other developers. See the [Initializing the Database](#initializing-the-database) section, below, before continuing to the next step in this section.
@@ -411,7 +410,7 @@ We use [GraphQL](https://graphql.org/) to define the API structure of the applic The GraphQL Playground has "Docs" and "Schema" tabs on the right side of the page. You can see them: * If you are already [**Running the Application**](#running-the-application) at http://localhost:5000/graphql -* If you don't have a running ap by visiting [GraphQL Playground](https://chapter-server.herokuapp.com/graphql). (Note, this is a free-tier of Heroku. Hit refresh every minute or two if the page fails to load and it should eventually "wake" the server.) +* If you don't have a running app at [GraphQL Playground](https://chapter-server.herokuapp.com/graphql). (Note, this is a free-tier of Heroku. Hit refresh every minute or two if the page fails to load and it should eventually "wake" the server.) ## Database @@ -453,14 +452,14 @@ Our DB commands closely mirror their Rails counterparts (there isn't anything qu #### Initializing the Database -If you're starting the application for the first time, you need to: -* (optionally) drop the database - to delete all the structure and data +If you're starting the application for the first time, or syncronizing with the latest development changes, then you like need to: +* drop the database - to delete all the structure and data * migrate the database - to structure by setup tables based on the schema * seed the database - development is easier with a database full of example entities. The process of creating example entities in the database is called seeding The `yarn db:reset` command will do all three tasks: drop, migrate, and seed. -If you prefer to run any or all of the steps manually, they are: +If you prefer to run some or all of the steps manually, then they are: * `yarn db:drop` * `yarn db:migrate` * `yarn db:seed` From 05a19f12bd1c30f57faac7d76aa94bbea14c2723 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Tue, 9 Mar 2021 00:42:00 -0500 Subject: [PATCH 08/10] Tweaks to the Docker Mode section of CONTRIBUTING.md --- CONTRIBUTING.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2103e79c70..c94c85da1f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -324,23 +324,26 @@ Ensure the Docker tools are installed: Make sure `IS_DOCKER=TRUE` is set in the `.env` file in your copy's root directory. -Run Docker Compose using `docker-compose up` and wait (this could take many minutes) for the logs show: +Run Docker Compose (`docker-compose up` on Linux) and wait for the successful output of as shown in the following example. + +This could take minutes for each line to appear. + > db_1 | ... LOG: database system is ready to accept connections -> ... +> +> > client_1 | ready - started server on http://localhost:3000 -> ... +> +> > app_1 | Listening on http://localhost:5000/graphql -The server will automatically restart anytime you save a `.ts` or `.js` file within the `server/` directory. - -You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` - -**(Note for Existing Contributors)** -If you (or someone else via a commit) updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. Then, run `docker-compose up` to start the container's services. +Once Docker is successfully running: +* The server will automatically restart anytime you save a `.ts` or `.js` file within the `server/` directory. +* You can run any command within the container by prefixing it with `docker-compose exec app`, e.g. `docker-compose exec app npm install express` +* If you, or someone else via a commit, updates `Dockerfile` or the contents of its build directory, run `docker-compose build` to get the new image. Then, run `docker-compose up` to start the container's services. ## Manual Mode -With this method you will manually managing the client-server, Postgres database, and API server. +With this method you will manually manage the client-server, Postgres database, and API server. This is a much lighter development footprint than Docker, but you need to run your own local Postgres DB. From 39f293750077f528367d7706dda72982192c208a Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Tue, 9 Mar 2021 00:47:10 -0500 Subject: [PATCH 09/10] Fix typos in CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c94c85da1f..fadece41e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -319,8 +319,8 @@ You can find more resources on Docker here: Ensure the Docker tools are installed: * For Windows & Mac, check Docker Desktop * For Linux -** Docker Engine using `docker --version` and it should output something like _Docker version 19.03.13..._ -** Docker Compose using `docker-compose --version` and it should output something like _docker-compose version 1.28.5..._ + * Docker Engine using `docker --version` and it should output something like _Docker version 19.03.13..._ + * Docker Compose using `docker-compose --version` and it should output something like _docker-compose version 1.28.5..._ Make sure `IS_DOCKER=TRUE` is set in the `.env` file in your copy's root directory. From 5852caa799831bcc1650501cd15de96e5946c531 Mon Sep 17 00:00:00 2001 From: Jim Ciallella <1777776+allella@users.noreply.github.com> Date: Tue, 9 Mar 2021 00:53:11 -0500 Subject: [PATCH 10/10] Fix additional typos in CONTRIBUTING.md --- CONTRIBUTING.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fadece41e4..bada683ff9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -324,9 +324,7 @@ Ensure the Docker tools are installed: Make sure `IS_DOCKER=TRUE` is set in the `.env` file in your copy's root directory. -Run Docker Compose (`docker-compose up` on Linux) and wait for the successful output of as shown in the following example. - -This could take minutes for each line to appear. +Run Docker Compose (`docker-compose up` on Linux) from the root project directory and wait for the successful output as shown in the following example. Note: this could take minutes for each line to appear. > db_1 | ... LOG: database system is ready to accept connections > @@ -430,7 +428,7 @@ We're using [Postgres](https://www.postgresql.org/) for our database and [TypeOR * If you're using a remote Postgres server, like [ElephantSQL](https://www.elephantsql.com/), then the Host and Port will be provided by the service. You'll also need to update the `DB_URL` value in your _.env_ file. ### Admin Tools -* [pgAdmin](https://www.pgadmin.org/), [Postico](https://eggerapps.at/postico/) or [Table Plus](https://tableplus.com/), can use the *** Host and Port** values above, based on your mode. +* [pgAdmin](https://www.pgadmin.org/), [Postico](https://eggerapps.at/postico/) or [Table Plus](https://tableplus.com/), can use your mode's **Host and Port** values as described above. * psql Client * In **Docker Mode**, `psql -h localhost -p 54320 -U postgres`. You don't have to run `docker-compose exec...` commands to "talk" to the Postgres container. * In **Manual Mode**, `psql -h localhost -p 543 -U postgres`