Skip to main content

​
Setup

The setup process will slightly differ depending on your operating system.

​
Step 1. Install Homebrew

The easiest way to install the required dependencies is to use Homebrew. Run the following command in your terminal:
zsh
We’ll use Homebrew to install:
  • PostgreSQL, our database.
  • Yarn, our TypeScript package manager.
  • uv, our Python package manager.

​
Step 2. Install required packages

PostgreSQL:
zsh
Yarn:
zsh
uv:
zsh

​
Step 3. Clone the Hoagie Help 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 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:
zsh
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:
uv
This creates a virtual environment named hoagie-help contained within the .venv directory. Activate this virtual environment with the following command:
venv
Then, install the backend dependencies with the following command:
zsh
This installs the required Python packages as specified in pyproject.toml 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
Then, run the following command:
zsh

​
Backend

In the base directory of the project, cd into the backend/ directory:
zsh
Then, run the following command:
uv
You’re all set! Happy coding. Be sure to check out the Development Workflow guide!
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:
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. Continue with the MacOS guide

From here, the steps are identical to the MacOS guide above. Open the Ubuntu terminal and follow the MacOS guide starting from Step 1. Install Homebrew.