Quickstart
Hoagie Plan
Learn how to set up your local development environment for Hoagie Plan
Setup
The setup process will slightly differ depending on your operating system.MacOS
MacOS
The easiest way to install the required dependencies is to use Homebrew.We’ll use Homebrew to install:
Bun:uv:
This installs the frontend dependencies as specified in This creates a virtual environment named Then, install the backend dependencies with the following command:This installs the required Python packages as specified in
Then, run the following command:Then, run the following command:
You’re all set! Happy coding.
Step 1. Install Homebrew
Run the following command in your terminal:zsh
- PostgreSQL, our database.
- Bun, our TypeScript package manager.
- uv, our Python package manager.
Step 2. Install required packages
PostgreSQL:zsh
zsh
zsh
Step 3. Clone the Hoagie Plan repository
We use GitHub for version control.zsh
NOTE: Environment variables are not included in cloned repositories.
Step 4. Environment variables
After you have the repository on your local device, you’ll need to add the environment variables.Frontend
In thefrontend/ directory, create a hidden file named .env.local.Backend
In thebackend/ 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:zsh
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:hoagie-plan contained within the .venv directory.
Activate this virtual environment with the following command:venv
zsh
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:zsh
zsh
Backend
In the base directory of the project,cd into the backend/ directory:zsh
You’re all set! Happy coding.
Windows
Windows
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.
We’ll use Homebrew to install:
Bun:uv:
This installs the frontend dependencies as specified in This creates a virtual environment named Then, install the backend dependencies with the following command:This installs the required Python packages as specified in
Then, run the following command:Then, run the following command:
You’re all set! Happy coding.
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:powershell
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:bash
- PostgreSQL, our database.
- Bun, our TypeScript package manager.
- uv, our Python package manager.
Step 5. Install required packages
PostgreSQL:bash
bash
bash
Step 6. Clone the Hoagie Plan repository
We use GitHub for version control.bash
NOTE: Environment variables are not included in cloned repositories.
Step 7. Environment variables
After you have the repository on your local device, you’ll need to add the environment variables.Frontend
In thefrontend/ directory, create a hidden file named .env.local.Backend
In thebackend/ 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:bash
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:hoagie-plan contained within the .venv directory.
Activate this virtual environment with the following command:venv
bash
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:bash
bash
Backend
In the base directory of the project,cd into the backend/ directory:bash
You’re all set! Happy coding.
Troubleshooting
Here are some common issues you might encounter when setting up your development environment.Scary-looking `psycopg2` error
Scary-looking `psycopg2` error
Ensure that you have After installation, verify that the PostgreSQL path is added to your If the path is missing, you can add PostgreSQL to your path by appending it directly to your shell configuration file (like Remember to source the file afterward to apply the changes immediately:
PostgreSQL installed on your system using Homebrew. You can install it by running:PATH environment variable to avoid issues. You can check this by running:.zshrc, .bash_profile, or .bashrc). For example:zsh
zsh
Undefined error when I navigate to pages other than homepage
Undefined error when I navigate to pages other than homepage