chore: revamp onboarding workflow w/ automated scripts 😮‍💨 (#101)

.github/workflows/ci.yml

@@ -14,9 +14,9 @@ jobs:
       postgres:
         image: postgres
         env:
-          POSTGRES_DB: colorstack
-          POSTGRES_PASSWORD: colorstack
-          POSTGRES_USER: colorstack
+          POSTGRES_DB: oyster
+          POSTGRES_PASSWORD: oyster
+          POSTGRES_USER: oyster
         ports:
           - 5432:5432
         options: >-
@@ -31,7 +31,7 @@ jobs:
           5s --health-retries 5
 
     env:
-      DATABASE_URL: postgres://colorstack:colorstack@localhost:5432/colorstack
+      DATABASE_URL: postgres://oyster:oyster@localhost:5432/oyster
       REDIS_URL: redis://localhost:6379
 
     steps:

CONTRIBUTING.md

@@ -13,61 +13,25 @@ their dreams of becoming software engineers. That being said, in order to make
 space for our community, we will be prioritizing all contributions from
 ColorStack members first, and then friends of ColorStack. ❤️
 
-## Your First PR
-
-Getting your first PR in is always the hardest. We're going to reduce that
-barrier for you! After you finish your local development setup (instructions
-below), your first PR can simply be updating the
-[`CONTRIBUTORS.yml`](./CONTRIBUTORS.yml) file with your GitHub username!
-
-You can name that PR:
-
-```
-chore: my first contribution ❤️
-```
-
-## Deciding What to Work On
-
-You can start by browsing through our list of
-[issues](https://github.com/colorstackorg/oyster/issues) or creating your own
-issue that would improve our product. Once you've decided on an issue, leave a
-comment and wait to get approval from one of our codebase admins - this helps
-avoid multiple people working on this same issue.
-
-## Making a Pull Request
-
-Some things to keep in mind when making a pull request:
-
-- The target branch in our repository is `main`.
-- Fill out the PR template accordingly.
-- The name of the PR should:
-  - Start with one of the following prefixes:
-    - `feat`: A non-breaking change which adds functionality.
-    - `fix`: A non-breaking change which fixes an issue.
-    - `refactor`: A change that neither fixes a bug nor adds a feature.
-    - `docs`: A change only to in-code or markdown documentation.
-    - `test`: A change that adds missing tests.
-    - `chore`: A change that is likely none of the above.
-  - Be in all lowercase.
-  - Start with a verb (ie: "add ...", "implement ...", "update ...").
-  - Have an emoji at the end of it (we like color around here). 🔥
-- Please check the
-  ["allow edits from maintainers option"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
-  when creating your PR. This allows us to more easily collaborate with you on
-  your work.
-- Most PRs should be attached to an issue, so be sure to add this to the PR
-  description:
-  ```
-  Closes #<ISSUE_NUMBER>.
-  ```
-  See more about
-  [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
-- A PR can only be merged (by a maintainer) if:
-  - A maintainer has reviewed and approved it.
-  - All CI checks have passed. See [this](./.github/workflows/ci.yml) workflow
-    for more details.
-  - All branches are up to date before merging.
-  - All conversations are resolved.
+## Table of Contents
+
+- [Local Development](#local-development)
+  - [Prerequisites](#prerequisites)
+  - [Fork and Clone Repository](#fork-and-clone-repository)
+  - [Project Dependencies](#project-dependencies)
+  - [Environment Variables](#environment-variables)
+  - [Database Setup](#database-setup)
+    - [Postgres Setup](#postgres-setup)
+    - [Executing Database Migrations](#executing-database-migrations)
+    - [Seeding the Database](#seeding-the-database)
+  - [Building the Project](#building-the-project)
+  - [Running the Applications](#running-the-applications)
+  - [Logging Into Applications](#logging-into-applications)
+  - [Editor Setup](#editor-setup)
+- [Making a Pull Request](#making-a-pull-request)
+  - [Your First PR](#your-first-pr)
+- [Deciding What to Work On](#deciding-what-to-work-on)
+- [License](#license)
 
 ## Local Development
 
@@ -77,10 +41,9 @@ To get started with local development, please follow these simple steps.
 
 Please ensure that you have the following software on your machine:
 
+- [Docker](https://docs.docker.com/engine/install)
 - [Node.js](https://nodejs.org/en/download/package-manager) (v20.x)
 - [Yarn](https://classic.yarnpkg.com/lang/en/docs/install) (v1)
-- [PostgreSQL](https://www.postgresql.org/download/) (v15.x)
-- [Redis](https://redis.io/docs/install/install-redis/)
 
 ### Fork and Clone Repository
 
@@ -91,28 +54,35 @@ Please ensure that you have the following software on your machine:
    ```
    git clone https://github.com/<YOUR_USERNAME>/oyster.git
    ```
-3. Create a new branch.
+3. [Configure the upstream repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork),
+   which will help you with
+   [syncing your fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
+   with the Oyster codebase as new code is added to it in the future.
+   ```
+   git remote add upstream https://github.com/colorstackorg/oyster.git
+   ```
+4. Create a new branch.
    ```
    git checkout -b YOUR_BRANCH_NAME
    ```
 
-### Syncing a Forked Repository
+### Project Dependencies
 
-In order to keep your forked repository up to date with the upstream repository,
-please read the following guides.
+To install all project dependencies, run:
 
-- [Configuring a Remote Repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-repository-for-a-fork)
-- [Syncing a Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
+```sh
+yarn
+```
 
 ### Environment Variables
 
-Set up your environment variable files by doing the following:
+To set up your environment variables, run:
 
-- In `/apps/admin-dashboard`, duplicate the `.env.example` to `.env`.
-- In `/apps/api`, duplicate the `.env.example` to `.env`.
-- In `/apps/member-profile`, duplicate the `.env.example` to `.env`.
-- In `/packages/core`, duplicate the `.env.test.example` to `.env.test`.
-- In `/packages/db`, duplicate the `.env.example` to `.env`.
+```
+yarn env:setup
+```
+
+You'll now have `.env` files in all of your apps (and a couple packages)!
 
 You'll notice that a lot of environment variables are empty. Most of these empty
 variables are tied to the 3rd party integrations we have with platforms such as
@@ -121,14 +91,6 @@ enable these integrations in development, please see the
 [How to Enable Integrations](./docs/how-to-enable-integrations.md)
 documentation.
 
-### Project Dependencies
-
-To install all project dependencies, run:
-
-```sh
-yarn
-```
-
 ### Database Setup
 
 You'll need to make sure that Postgres and Redis are running in the background.
@@ -138,13 +100,7 @@ You'll need to make sure that Postgres and Redis are running in the background.
 To set up your Postgres databases, you can run:
 
 ```
-yarn db:setup
-```
-
-You should now be able to connect to your database like this:
-
-```sh
-psql colorstack -U colorstack
+yarn dx:up
 ```
 
 #### Executing Database Migrations
@@ -224,6 +180,63 @@ life a bit easier:
 - [Tailwind IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
 - [Typescript Importer](https://marketplace.visualstudio.com/items?itemName=pmneo.tsimporter)
 
+## Making a Pull Request
+
+Some things to keep in mind when making a pull request:
+
+- The target branch in our repository is `main`.
+- Fill out the PR template accordingly.
+- The name of the PR should:
+  - Start with one of the following prefixes:
+    - `feat`: A non-breaking change which adds functionality.
+    - `fix`: A non-breaking change which fixes an issue.
+    - `refactor`: A change that neither fixes a bug nor adds a feature.
+    - `docs`: A change only to in-code or markdown documentation.
+    - `test`: A change that adds missing tests.
+    - `chore`: A change that is likely none of the above.
+  - Be in all lowercase.
+  - Start with a verb (ie: "add ...", "implement ...", "update ...").
+  - Have an emoji at the end of it (we like color around here). 🔥
+- Please check the
+  ["allow edits from maintainers option"](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
+  when creating your PR. This allows us to more easily collaborate with you on
+  your work.
+- Most PRs should be attached to an issue, so be sure to add this to the PR
+  description:
+  ```
+  Closes #<ISSUE_NUMBER>.
+  ```
+  See more about
+  [linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+- A PR can only be merged (by a maintainer) if:
+  - A maintainer has reviewed and approved it.
+  - All CI checks have passed. See [this](./.github/workflows/ci.yml) workflow
+    for more details.
+  - All branches are up to date before merging.
+  - All conversations are resolved.
+
+### Your First PR
+
+Getting your first PR in is always the hardest. Lucky for you, we love quick
+wins here at ColorStack, so we're going to reduce that barrier for you! After
+you finish your [local development](#local-development) setup, your first PR can
+simply be updating the [`CONTRIBUTORS.yml`](./CONTRIBUTORS.yml) file with your
+GitHub username!
+
+You can name that PR:
+
+```
+chore: my first contribution ❤️
+```
+
+## Deciding What to Work On
+
+You can start by browsing through our list of
+[issues](https://github.com/colorstackorg/oyster/issues) or creating your own
+issue that would improve our product. Once you've decided on an issue, leave a
+comment and wait to get approval from one of our codebase admins - this helps
+avoid multiple people working on this same issue.
+
 ## License
 
 By contributing your code to the this GitHub repository, you agree to license

apps/admin-dashboard/.env.example

@@ -2,7 +2,7 @@
 
 ADMIN_DASHBOARD_URL=http://localhost:3001
 API_URL=http://localhost:8080
-DATABASE_URL=postgresql://colorstack:colorstack@localhost:5432/colorstack
+DATABASE_URL=postgresql://oyster:oyster@localhost:5433/oyster
 ENVIRONMENT=development
 JWT_SECRET=_
 REDIS_URL=redis://localhost:6379

apps/api/.env.example

@@ -1,7 +1,7 @@
 # Required to run the API in development...
 
 API_URL=http://localhost:8080
-DATABASE_URL=postgresql://colorstack:colorstack@localhost:5432/colorstack
+DATABASE_URL=postgresql://oyster:oyster@localhost:5433/oyster
 ENVIRONMENT=development
 JWT_SECRET=_
 REDIS_URL=redis://localhost:6379

apps/member-profile/.env.example

@@ -1,7 +1,7 @@
 # Required to run the Member Profile in development...
 
 API_URL=http://localhost:8080
-DATABASE_URL=postgresql://colorstack:colorstack@localhost:5432/colorstack
+DATABASE_URL=postgresql://oyster:oyster@localhost:5433/oyster
 ENVIRONMENT=development
 JWT_SECRET=_
 REDIS_URL=redis://localhost:6379

config/tailwind/package.json

@@ -8,7 +8,7 @@
     "@tailwindcss/container-queries": "^0.1.1"
   },
   "devDependencies": {
-    "prettier-plugin-tailwindcss": "^0.5.4",
+    "prettier-plugin-tailwindcss": "^0.5.13",
     "tailwindcss": "^3.4.3"
   }
 }

docker-compose.yml

@@ -0,0 +1,42 @@
+# This file helps us easily spin up our Postgres and Redis databases in local
+# development (this is not meant to be used in production), bypassing the need
+# to install and configure these services on our local machines.
+
+version: '3.9'
+
+services:
+  postgres:
+    container_name: oyster-postgres
+    image: postgres:15-alpine
+    ports:
+      # We're using port 5433 to avoid any potential conflicts.
+      - 5433:5432
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: oyster
+      POSTGRES_PASSWORD: oyster
+      POSTGRES_USER: oyster
+
+  postgres-test:
+    container_name: oyster-postgres-test
+    image: postgres:15-alpine
+    ports:
+      # We're using port 5434 to avoid any potential conflicts.
+      - 5434:5432
+    environment:
+      POSTGRES_DB: oyster_test
+      POSTGRES_PASSWORD: oyster
+      POSTGRES_USER: oyster
+
+  redis:
+    container_name: oyster-redis
+    image: redis:latest
+    ports:
+      - 6379:6379
+    volumes:
+      - redis_data:/data
+
+volumes:
+  pg_data:
+  redis_data:

docs/how-to-implement-a-database-migration.md

@@ -49,6 +49,7 @@ Error: corrupted migrations: previously executed migration <SOME_MIGRATION_NAME>
 
 The easiest way to fix this is to re-setup your database by running:
 
-```
-yarn db:setup
+```sh
+yarn dx:nuke
+yarn dx:up
 ```

package.json

@@ -8,17 +8,20 @@
     ]
   },
   "scripts": {
-    "prepare": "husky install",
     "build": "turbo run build --cache-dir=.turbo",
     "db:migrate": "yarn workspace @oyster/db migrate",
     "db:migration:create": "yarn workspace @oyster/db migration:create",
     "db:seed": "yarn workspace @oyster/db seed",
-    "db:setup": "yarn workspace @oyster/db setup",
     "db:types": "yarn workspace @oyster/db types",
     "dev": "turbo run dev --cache-dir=.turbo",
     "dev:apps": "yarn dev --filter='./apps/*'",
+    "dx:down": "docker compose down",
+    "dx:nuke": "docker compose down --volumes --remove-orphans",
+    "dx:up": "docker compose up -d",
+    "env:setup": "yarn workspace @oyster/scripts env:setup",
     "lint": "turbo run lint --cache-dir=.turbo",
     "lint:fix": "turbo run lint:fix --cache-dir=.turbo",
+    "prepare": "husky install",
     "start": "turbo run start --cache-dir=.turbo",
     "test": "turbo run test --cache-dir=.turbo",
     "type-check": "turbo run type-check --cache-dir=.turbo"

packages/core/.env.test.example

@@ -1,2 +1,2 @@
-DATABASE_URL=postgresql://colorstack:colorstack@localhost:5432/colorstack_test
+DATABASE_URL=postgresql://oyster:oyster@localhost:5434/oyster_test
 ENVIRONMENT=test

packages/db/.env.example

@@ -1,4 +1,4 @@
 # This is only needed for automatically generating types from the database
 # using `kysely-codegen`. See the following:
 # https://github.com/RobinBlomberg/kysely-codegen?tab=readme-ov-file#generating-type-definitions
-DATABASE_URL=postgresql://colorstack:colorstack@localhost:5432/colorstack
+DATABASE_URL=postgresql://oyster:oyster@localhost:5433/oyster

packages/db/.eslintrc.cjs

@@ -1,6 +1,7 @@
 /** @type {import("eslint").Linter.Config} */
 module.exports = {
   extends: ['@oyster/eslint-config/base'],
+  ignorePatterns: ['*.js'],
   overrides: [
     {
       files: ['./src/migrations/*'],