The easiest way to install the required dependencies is to use Homebrew.

Step 1. Install Homebrew

Run the following command in your terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

We’ll use Homebrew to install:

• PostgreSQL, our database.
• Bun, our TypeScript package manager.
• uv, our Python package manager.

For more information on our tech stack, please visit our tech stack page.

Step 2. Install required packages

PostgreSQL:

brew install postgresql@17 # Latest version

Bun:

brew install oven-sh/bun/bun

uv:

brew install uv

Step 3. Clone the Hoagie Plan repository

We use GitHub for version control.

git clone https://github.com/hoagieclub/plan.git

Step 4. Environment variables

After you have the repository on your local device, you’ll need to add the environment variables.

Frontend

In the frontend/ directory, create a hidden file named .env.local.

Backend

In the backend/ directory, create a hidden file named .env.

Values

See the Slack for the values for these environment variables. Once you have access to the files, paste them in as is.

There are template files for the frontend and the backend — .env.local.example and .env.example, respectively — so that you know which values the app is expecting.

Step 5. Downloading dependencies

You will need to download the required dependencies before you can run the app.

Frontend

In the base directory of the project, cd into the frontend/ directory and run the following command:

bun install

This installs the frontend dependencies as specified in package.json to ensure consistent package versions across environments.

Backend

In the base directory of the project, cd into the backend/ directory.

Then, create a virtual environment using the following command:

This creates a virtual environment named hoagie-plan contained within the .venv directory. Activate this virtual environment with the following command:

source .venv/bin/activate

Then, install the backend dependencies with the following command:

uv sync

This installs the required Python packages as specified in pyproject.toml, requirements.txt, and uv.lock to ensure consistent package versions across environments.

Step 6. Running the app

You will need to run the frontend and backend applications simultaneously.

Frontend

In the base directory of the project, cd into the frontend/ directory:

cd frontend

Then, run the following command:

bun run dev

Backend

In the base directory of the project, cd into the backend/ directory:

cd backend

Then, run the following command:

You’re all set! Happy coding.

It is a bit of a nightmare to get the Windows environment set up.

We’ve found the fastest workaround to be installing the Windows Subsystem for Linux (WSL). For more details, see this article.

Step 1. Open PowerShell or Windows Command Prompt

You must do this in administrator mode by right-clicking and selecting “Run as administrator”.

Step 2. Installing WSL

Run the following command:

wsl --install

Step 3. Open Ubuntu

Open the Start Menu, search for Ubuntu (or the name of the Linux distribution you installed), and click on the app to open it.

When you launch Ubuntu for the first time, it will take a few minutes to set up, and you may be prompted to create a new username and password for your Linux environment.

Step 4. Install Homebrew

From here, the steps should be identical to the MacOS guide above.

The easiest way to install the required dependencies is to use Homebrew.

Run the following command in your terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

We’ll use Homebrew to install:

• PostgreSQL, our database.
• Bun, our TypeScript package manager.
• uv, our Python package manager.

For more information on our tech stack, please visit our tech stack page.

Step 5. Install required packages

PostgreSQL:

brew install postgresql@17 # Latest version

Bun:

brew install oven-sh/bun/bun

uv:

brew install uv

Step 6. Clone the Hoagie Plan repository

We use GitHub for version control.

git clone https://github.com/hoagieclub/plan.git

Step 7. Environment variables

After you have the repository on your local device, you’ll need to add the environment variables.

Frontend

In the frontend/ directory, create a hidden file named .env.local.

Backend

In the backend/ directory, create a hidden file named .env.

Values

See the Slack for the values for these environment variables. Once you have access to the files, paste them in as is.

There are template files for the frontend and the backend — .env.local.example and .env.example, respectively — so that you know which values the app is expecting.

Step 8. Downloading dependencies

You will need to download the required dependencies before you can run the app.

Frontend

In the base directory of the project, cd into the frontend/ directory and run the following command:

bun install

This installs the frontend dependencies as specified in package.json to ensure consistent package versions across environments.

Backend

In the base directory of the project, cd into the backend/ directory.

Then, create a virtual environment using the following command:

This creates a virtual environment named hoagie-plan contained within the .venv directory. Activate this virtual environment with the following command:

source .venv/bin/activate

Then, install the backend dependencies with the following command:

uv sync

This installs the required Python packages as specified in pyproject.toml, requirements.txt, and uv.lock to ensure consistent package versions across environments.

Step 9. Running the app

You will need to run the frontend and backend applications simultaneously.

Frontend

In the base directory of the project, cd into the frontend/ directory:

cd frontend

Then, run the following command:

bun run dev

Backend

In the base directory of the project, cd into the backend/ directory:

cd backend

Then, run the following command:

You’re all set! Happy coding.

Ensure that you have PostgreSQL installed on your system using Homebrew. You can install it by running:

brew install postgresql

After installation, verify that the PostgreSQL path is added to your PATH environment variable to avoid issues. You can check this by running:

echo $PATH

If the path is missing, you can add PostgreSQL to your path by appending it directly to your shell configuration file (like .zshrc, .bash_profile, or .bashrc). For example:

echo 'export PATH="/usr/local/opt/postgresql/bin:$PATH"' >> ~/.zshrc

Remember to source the file afterward to apply the changes immediately:

source ~/.zshrc

Make sure the environment variables, .env.local and .env, are set at the root level of the frontend/ and backend/ directories, respectively.