Skip to content

Onboarding for Devs (MacOS)

Jump to bottom
danny2637 edited this page Jun 2, 2025 · 4 revisions

Preliminaries

If at any point during installation of the preliminaries, you run into issues with the curl command, ensure that running which curl returns /usr/bin/curl.

  1. Download VSCode

  2. Homebrew if you don't have it

    • IF you have an M1 Mac and your computer 'inherited' homebrew from a non-M1 device you will likely need to reinstall homebrew:
      • To uninstall: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/uninstall.sh)"
      • To reinstall: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    • After the installation, your terminal will prompt you to run three commands; run them. If there's no output following those 3 you're probably good 👍
    • To verify installation worked, run brew -v which will print the installed version of homebrew.

  3. Ensure XCode is installed from the app store (M2 Macs probably don't need)

  4. XCode Command Line Tools (everyone)

    • xcode-select --install

  5. Python dependencies

    • Run: brew install openssl readline sqlite3 xz zlib tcl-tk

  6. If you don't have git already, go git it 🤪

    • brew install git
    • Github Desktop
      • Note for apple silicon: make sure you select the Apple Silicon link that is somewhat hidden below the big purple download button

  7. Python 3.12 using asdf

    1. Install asdf:
      • git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
      • Append to your .zshrc file by running:
      printf "\n# asdf completions etc" >> ~/.zshrc
printf "\n. \"$HOME/.asdf/asdf.sh\"" >> ~/.zshrc
printf "\nfpath=(${ASDF_DIR}/completions $fpath)" >> ~/.zshrc
printf "\nautoload -Uz compinit && compinit\n" >> ~/.zshrc
      • Restart your terminal
      • If you are not using zsh or have issues, check installation steps here
    2. Add the Python plugin with asdf plugin add python
    3. now you're able to install specific python versions. We want Python 3.12 though, so to see the list of available 3.12 releases, run asdf list all python 3.12 - The rest of this guide assumes you have installed Python 3.12.4
    4. Now to actually install, run asdf install python 3.12.4

  8. Node 22.3.0

    • Managed with asdf:
      • Run the following commands:
      asdf plugin add nodejs
asdf install nodejs 22.3.0
      • If you have a global version of node you'd like your machine to be running, you may set it by running the following: asdf global nodejs <VERSION>, assuming you installed that version with asdf already.

  9. The backend is scaffolded with Postgres

    • install by running:
      • brew install postgresql@14
      • then brew install --cask pgadmin4

  10. Fork both project repositories:

    1. Backend
    2. Frontend
    • When you do this, it will give you the option to make a name. Make sure to include your first and last name to make it easier to find

  11. Clone your forks (not the upstream, i.e., not the Lab Lab Lab repos)

    1. You can find the appropriate URL by clicking on the green 'Code' button at the top right of your Github screen. Ensure that the 'Local' tab at the top is selected, and unless you have made github aware of any SSH keys, choose HTTPS and copy that link.
    2. Use VSCode's source control features to clone:
      • By following this guide
        • Note: you need not go past "Clone a repository locally" in the linked guide above.
      • When selecting a folder on your computer for the clones, make a new folder to hold both clones
    3. Once cloned, run the following from a terminal within your clones' directories as a smoke test git remote -v
      • Ensure that the outputted lines beginning with origin are followed by your fork's URL and not ...Lab-Lab-Lab/...

Backend Setup

  1. Setting your python version for the project

    • We didn't forget about our good friend asdf
      1. from your terminal, cd to the parent directory of your backend clone
      2. run asdf local python 3.12.4
        • verify that did the trick by running python --version.

  2. Database configuration with pgadmin4

    1. Launch pgadmin4
      • Note: if you installed pgadmin4 with homebrew as the guide suggested above, your username and password are your MacOS username and password, otherwise the username is most likely postgres and you would have been prompted for a master password during install.
    2. On the pgadmin dashboard/landing page, click "Create a Server"
      • Under the General tab, give the server a meaningful nam, MusicCPR is probably a pretty good one
      • Under the Connection tab, enter localhost in for Host name/address, and ensure that the Port is set to 5432
      • Still within the Connection tab, enter your username/password (see note above underneath "Launch pgadmin4")
    3. Create a new database using pgadmin4:
      • Right click your newly created server, then select Create > Database
        • Enter a name, I'm just using teleband
        • ensure the Owner is yourself/the user you have been using thus far
        • Save 💾

  3. Making your local clone 'aware' of the database

    • Create a new file called .env in the CPR-Music-Backend directory
    • Add one of the two following lines:
      1. if you did not specify a master password when setting up pgadmin4 (i.e., you installed using homebrew)
        • DATABASE_URL=postgres:///teleband
      2. if you specified a master password when setting up pgadmin4 (i.e., you did not install using homebrew)
        • DATABASE_URL=postgres://user:pass@localhost/teleband
        • where user and pass are the username and password you have been using thus far.

  4. Fetch the accompaniments and sample_audio folders from this Backend-Media

    • Copy this repo to a different place (don't want to copy a repo into a repo, Repoception🤯)
    • Create a new folder within the teleband folder in your backend clone called media
    • paste the two folders in there
      • Ensure that the newly created folders are "greyed out" in the VSCode file explorer side pane

  5. Setting up the venv (Virtual Environment)

    • In your terminal:
      1. cd .. to the parent directory of your backend clone
      2. create your venv by running python -m venv musenv
      3. cd back into your backend clone (try cd - to cd into the last directory)

  6. Activate the venv note: you will need to do this frequently, i.e., each time you start working on the project

    • run source ../musenv/bin/activate
      • If the command is successful, your shell prompt should now be prefixed with musenv (assuming you chose the name musenv for your venv)

  7. Server Setup

    1. Upgrade pip with pip install --upgrade pip
    2. Install backend dependencies with pip install -r requirements/local.txt (this can take a minute 🥱)
    3. If you're still awake (just kidding it doesn't take that long), run python manage.py migrate
    4. Now, create a superuser for the django-administration pages, python manage.py createsuperuser
      • do not forget the username/password you choose here
      • the email you choose does not need to be real (but it does have to validate)

  8. Run the server 🏃

    • Run python manage.py runserver

    • Cross your fingers

      • If all is swell you should see some output like the following:
      System check identified no issues (0 silenced).
May 17, 2024 - 22:26:26
Django version 3.2.11, using settings 'config.settings.local'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Frontend Setup

  1. cd into your frontend clone, or use the integrate terminal after opening the frontend clone in VSCode

  2. Run npm i

    • This will install all dependencies listed in package.json (and the dependencies' dependencies and so on... 🔄)

  3. Create a file in the root of the frontend called, .env.local and make the contents:

    SECRET=idkjustpleasehavesomethingfortesting
NEXTAUTH_URL="http://localhost:3000"

  4. To run the frontend, just run npm run dev

Launching it All

  1. Ensure the backend is still running, if not, run python manage.py runserver from within your backend clone
  2. run npm run dev
  3. In a browser (aka firefox 🦊), navigate to http://localhost:3000
  4. Everything, should be wunderbar
    • Celebrate 🥳

Quotidian (Daily) Setup

  1. Check that your forks are up to date
    1. Go to your fork's webpage on github, if you see a line that says "this branch is X commits behind JMU-CIME/...", then click the fun "Sync fork" button to the right 🚰
  2. Activate your environment
    1. cd into your backend clone
    2. run source ../musenv/bin/activate
  3. Run the backend:
    1. still within your backend clone,
    2. run python manage.py runserver
    3. Do not quit/kill the backend while working ☠️
  4. Run the frontend:
    1. cd to your frontend clone
    2. run npm run dev
    3. Navigate to http://localhost:3000

Enjoy coding 🤗

Clone this wiki locally