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.

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.

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.

Some issues (like ports already being in use) can be fixed by making adjustments to the configuration in this file. This configuration is specific to your machine: make sure they don't end up in a pull request!

Set Up OAuth

For AUTH_CLIENT_ID and AUTH_CLIENT_SECRET, you can get these from the DevDogs website. Go to <devdogsuga.org> and sign in.

Then, navigate to the settings by clicking on your profile avatar, and copy the client ID and client secret from the API keys page. (You may need to generate a new client secret; they're only visible once!)

That's it!

Now that you've followed these steps, you have all of the set up to run the project locally. Get started by executing pnpm run dev from the project directory in your terminal!

Notes and troubleshooting

• If port 3306 is already in use on your machine, change the port on which MySQL runs by updating MYSQL_PORT 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.

---