Guide: Getting Started

Follow this guide so that you can work on the Community Resource Forum project on your own computer.

VSCode (optional)

You will need an IDE for writing code. A widely used and high-quality one is Visual Studio Code, or VSCode, but you can use a different one if you prefer. If you choose VSCode, you will have several options for additional components during installation. For now, you only need to select the options related to this project's tech stack (e.g. Git, Node.js).

Fork repository

In order to contribute to the project, you will need to create your own fork of it on GitHub. To do this, go to the repository on GitHub and click fork. Do not select the "copy main branch only" option—development will be done on the dev branch rather than main, so you want to copy the dev branch as well.

Git

Git will allow you to contribute code to the project repository. You can find the correct Git installation for your operating system here. Once you have installed Git and cd into your preferred file directory, you can clone your fork of the project repository from the command line (Command Prompt on Windows) using git clone https://github.com/[your username]/Community-Resource-Forum.git. Then cd into the Community-Resource-Forum folder and 'checkout' to the dev branch using git checkout dev. Now, you can move changes from your computer (local files) to your fork (cloud) on GitHub using git add, git commit, and git push in your terminal (or GitHub Desktop if you prefer a GUI). Pictures below:

If you are using MacOS, I would recommend installing homebrew with this command /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)". Once it is installed you can run brew install git.

Adding additional branches from original repo

If you only have main on your forked repository (cloud), then please run the following commands to add the dev branch:

git remote add upstream https://github.com/DevDogs-UGA/Community-Resource-Forum.git

git fetch upstream dev

git checkout -b dev upstream/dev

More information on commonly used Git commands can be found here, and more information about authenticating to GitHub can be found here.

Node.js

We are using Next.js for the frontend and backend of our project, and Node.js is a requirement for Next.js. You can install Node.js here.

pnpm

Node.js comes with a built-in package manager called npm. However, we recommend you use pnpm instead. Both package managers function the same way, but pnpm has better performance. After you have installed Node.js, you can install pnpm from the command line using the instructions for your device on their website.

Drizzle and other dependencies

Once you've installed pnpm, you can install Drizzle and all other dependencies for our project from the command line (terminal). To do this, change directories into the root directory of the project repository (the name of the folder should be Community-Resource-Forum) and run pnpm install. This will install the project's dependencies, including Drizzle.

Google OAuth

In order to sign in to the community resource forum website on your own computer for testing, you will need to set up a Google OAuth client. A guide on how to do this can be found here. When asked for an authorized redirect URI, put http://localhost:3000/api/auth/callback/google. Once you've created your OAuth client, save the client ID and secret, as you will need them in the next step.

Step 1: Create a project. This can just be called DevDogs, however the name does not matter.

Step 2: Use the search bar to navigate to Google Auth Platform

Step 3: Navigate to Clients and click get started

Step 4: Insert DevDogs as AppName and put your personal email into user support email and contact email. Select External Audience and create!

Step 5: Create a Client

Step 6: Select Web Application, Insert Name as DevDogs (doesn't matter), and put http://localhost:3000/api/auth/callback/google into the redirect url.

Step 7:

Create and save your Client Id and Client Secret. This information will be useful to fill out the .env file later!

Set up .env file

In order to run the project on your computer, you will need to specify some environment variables in a .env file. To do this, first create a copy of the .env.example file and rename the copied file .env, and then add values to the variables in this .env file. For AUTH_GOOGLE_ID, put your Google OAuth client ID. For AUTH_GOOGLE_SECRET, put your Google OAuth client's secret. For MYSQL_PASSWORD you can keep it as "password". This will just be on your local machine. For MYSQL_DATABASE keep it as "devdogs". Finally for port MYSQL_PORT="" you can put whatever free port you have available (eg. 3006).

Install Docker

Docker makes it easy to run services (like MySQL) in a containerized environment.

• Download and install Docker Desktop for macOS: https://www.docker.com/products/docker-desktop/

• After installing, open Docker Desktop and wait until it reports "Docker is running" (whale icon in the menu bar).

• If you're on Apple Silicon (M1/M2), Docker Desktop will run natively; no extra steps are required in most cases.

Windows Only

• Windows requires WSL 2 backend for best compatibility. During Docker Desktop installation you can enable the WSL 2 feature and install a Linux kernel update.

• To check if you have wsl (Windows Subsystem for Linux), run wsl --version in Command Prompt (or preferred terminal environment)

• If you do not have wsl, you can install it with wsl --install in the terminal. Then restart your machine.

Install Docker Desktop with the instructions here (pictures below. Then ensure WSL 2 is enabled and Docker is configured to use the WSL 2 backend (Docker Desktop settings > General / Resources)

Pictures below for Windows:

After running Docker Desktop Installer.exe (it takes a bit):

After restart, open Docker Desktop, and create an account and/or login. Then click the settings icon:

Scroll down to the below option and confirm that WSL 2 base engine is checked (if your system supports it, it will be default applied)

If it's not checked, click it and hit "Apply":

Now docker commands work from Windows using the new WSL 2 engine and you can run Docker.

That's it!

Now that you've followed these steps, you have all of the set up to run the project locally. Check the Run section below.

Run

Visit Booting the Project on Local

Notes and troubleshooting

• If port 3306 is already in use on your machine, change the host port mapping (for example -p 3307:3306) and update DATABASE_URL in your .env accordingly.
• On Windows, if you use Command Prompt instead of PowerShell/WSL, the line-continuation backslashes () won't work—either run the commands in PowerShell/WSL or paste the full docker run command on one line.
• If you want the container to persist data across restarts, add a volume mount: -v devdog-mysql-data:/var/lib/mysql to the docker run command.

---