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.
Step 1. Install Homebrew
Run the following command in your terminal:
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:
Bun:
uv:
Step 3. Clone the Hoagie Plan repository
We use GitHub for version control.
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 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:
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:
Then, install the backend dependencies with the following command:
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:
Then, run the following command:
Backend
In the base directory of the project, cd into the backend/ directory:
Then, run the following command:
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.
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:
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:
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:
Bun:
uv:
Step 6. Clone the Hoagie Plan repository
We use GitHub for version control.
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 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:
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:
Then, install the backend dependencies with the following command:
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:
Then, run the following command:
Backend
In the base directory of the project, cd into the backend/ directory:
Then, run the following command:
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 PostgreSQL installed on your system using Homebrew. You can install it by running:
After installation, verify that the PostgreSQL path is added to your PATH environment variable to avoid issues. You can check this by running:
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:
Remember to source the file afterward to apply the changes immediately:
Undefined error when I navigate to pages other than homepage
Undefined error when I navigate to pages other than homepage