Hackathon night · local-first · clone, run, then git
Two repos. One source folder. Two processes. Then a branch.
Clone hackathon-site and hackathon-api next to each other,
start the desktop site on :5500 and the API on :8080,
then work on a branch, push it, and merge into main.
Do not open HTML as file:// — the browser will block the API.
Do the numbered steps in order. Jump to troubleshooting only when a command fails.
Two repos, static site, JSON API. The linked wiki is Docs in the nav.
HTML + styles.css. New JavaScript is Alpine.js 3 from a CDN (no npm).
Leaflet draws the map.
Alpine.js
·
site stack.
Python 3.12, Uvicorn, Docker, Cloud Run in London.
/health and /test_field.
API in the wiki
·
Alpine test page.
Install these, then close and reopen PowerShell so PATH updates stick.
Git for Windows. After install, a new terminal should print a version for git --version.
From python.org, not the Microsoft Store stub. Tick Add python.exe to PATH. Prefer the py launcher if python is broken.
You must be able to see Tyneside-Software/hackathon-site and hackathon-api while signed in. A 404 means you are not in the org, or you are signed into the wrong GitHub account.
Windows PowerShell 5.1 is enough. Run commands from a folder you own — never from C:\Windows\System32.
Sanity check in a new PowerShell window:
git --version
py --version
python --version
whoami
Get-Location
git and at least one of py / python must print a real version
(3.10+). Get-Location must not be System32. If Python opens the Store, skip to
Fix: Python is the Store stub.
The start script looks next door for the API. The folder names must be exact, and they must be siblings — not one inside the other.
Use source under your user profile. Any parent is fine as long as both clones
sit directly inside it. Do not clone into Downloads, Program Files, or the Windows directory.
mkdir $env:USERPROFILE\source
cd $env:USERPROFILE\source
Get-LocationYou should now be in C:\Users\<you>\source.
HTTPS (typical):
git clone https://github.com/Tyneside-Software/hackathon-site.git
git clone https://github.com/Tyneside-Software/hackathon-api.gitClone from the Tyneside-Software org, not a personal fork, unless someone has told you otherwise.
start.ps1 expectsFrom source:
Get-ChildItem
Test-Path .\hackathon-site\start.ps1
Test-Path .\hackathon-api\app\main.pyBoth Test-Path lines must print True. The tree is:
C:\Users\<you>\source\
hackathon-site\ ← front end (this website)
start.ps1
index.html
onboarding.html
app\
hackathon-api\ ← back end
app\main.py
requirements.txtsource\hackathon-site\hackathon-api
(nested). The start script will not find app\main.py.
One command starts both processes. It opens two PowerShell windows and your browser. Close those two windows to stop the servers — closing the launcher is not enough.
cd $env:USERPROFILE\source\hackathon-site
.\start.ps1
First run creates hackathon-api\.venv, installs FastAPI / uvicorn,
then serves:
If PowerShell refuses to run the script, see Fix: running scripts is disabled.
Tick these before you start editing. If any fail, go to troubleshooting with the exact error text.
:5500.:8080/health returns JSON with ok: true.http://127.0.0.1:..., never file://..\start.ps1.hackathon-api\.venv exists after the first successful start.
When those pass, do not keep stacking commits on main.
Pull, branch, push the branch, then merge into main —
the git steps below.
Commands below use hackathon-site. Repeat the same sequence in
hackathon-api when the card is backend work.
Never force-push main.
main from GitHub before you start.
main.
main, then everyone pulls.
Git will refuse to commit until user.name and user.email exist.
Set them locally so you do not overwrite a teammate’s global config:
cd $env:USERPROFILE\source\hackathon-site
git config user.name "Your Name"
git config user.email "you@example.com"
git config --local --get-regexp user.Use the name and email on your GitHub account. Repeat in hackathon-api.
main so you start current
git pull downloads new commits from GitHub and joins them into your current branch.
Always do this on main before you branch, and again before you merge.
cd $env:USERPROFILE\source\hackathon-site
git status
git checkout main
git pull origin main
git status should say you are on main and
working tree clean. If you have leftover local edits, commit or stash them first —
pull will refuse to overwrite them. Same commands in the API repo when you need it.
Later, when you already have local commits that GitHub does not, and Git rejects a push with “non-fast-forward”, update with rebase instead of a messy extra merge:
git pull --rebase origin mainThat replays your commits on top of theirs. Do not git push --force to main.
A branch is a named line of commits. main stays the working site;
your card lives on the branch until it is ready to merge.
Name it <you>/<short-topic> so the rest of the table can see who owns it.
git checkout main
git pull origin main
git checkout -b reeve/onboarding-git
git status
git branch
git checkout -b creates the branch and switches you onto it.
git status should now say On branch reeve/onboarding-git
(use your name and topic). The star in git branch is the branch you are on.
Switch later with git checkout main or git checkout reeve/onboarding-git.
main unless you have been told to.
If you already did, see Fix: I committed on main by mistake.
Change the files for the card. Refresh http://127.0.0.1:5500/ and confirm Home, Map, and Board still load. Then commit named files, not a blind add of everything:
git status
git add onboarding.html
git commit -m "Add git pull, branch, push, and merge steps to onboarding."
git log -1 --oneline
In hackathon-api, .venv and .env are gitignored — leave them untracked.
Check git status before you add. The commit lives only on your machine until you push.
Push publishes your branch so others (and the merge) can see it.
The first push of a new branch needs -u to set the upstream:
git push -u origin reeve/onboarding-git
After that, more commits on the same branch are just git push.
Check GitHub: you should see the branch on
hackathon-site
(or the API repo). You have not changed main yet.
If GitHub already has commits you do not, pull the branch first
(git pull once upstream is set), then push.
main into your branch if it movedWhile you worked, someone else may have merged. Update your branch so the later merge is small:
git checkout reeve/onboarding-git
git fetch origin
git merge origin/main
git push
If Git stops on a conflict, it lists the files. Open each, keep the right lines
(both sides if both belong), delete the <<<<<<< / ======= /
>>>>>>> markers, then:
git add path\to\fixed-file
git status
git commit
git pushThe site must still load after you resolve. Do not skip a conflicted file.
main
Two equivalent ways. Use a pull request if someone else should glance at the diff;
merge locally if you are landing a small card and main is quiet.
A — GitHub pull request (preferred when two people finish at once)
main ← compare your branch.git checkout main
git pull origin mainB — merge locally, then push main
git checkout main
git pull origin main
git merge reeve/onboarding-git
# refresh localhost — Home / Map / Board still work
git push origin main
git merge brings the branch commits onto main.
If GitHub’s main moved after your pull, the push is rejected — do
git pull --rebase origin main (or merge origin/main), confirm the site, then push again.
Never --force on main.
Once it is on main, the branch is done:
git checkout main
git pull origin main
git branch -d reeve/onboarding-git
git push origin --delete reeve/onboarding-git
-d refuses if the branch never merged — that is a safety rail.
Everyone else runs git checkout main then git pull origin main
in both repos before starting the next card.
main as the default loop.
Branch → push branch → merge → everyone pulls.
Force-push, rewriting published history, and “I will just overwrite theirs” are out.
Open the row that matches what you saw. Most failures on this stack are PATH, folder layout, execution policy, or a port still held by an old window.
Error looks like:
.\start.ps1 : File cannot be loaded because running scripts is disabled on this system.Allow your own scripts (once per machine):
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedOr run this copy without changing policy:
powershell -ExecutionPolicy Bypass -File .\start.ps1Typical messages:
Python was not found; run without arguments to install from the Microsoft Store.
py : The term 'py' is not recognized as the name of a cmdlet.The Store alias under WindowsApps is not a real interpreter. Install Python from python.org, tick Add python.exe to PATH, then close every terminal and open a new one.
Check:
py --list
py -3 --version
Get-Command python | Format-List Source
If python still points at WindowsApps but py -3 works, use py -3
for any manual server commands. For start.ps1 (which calls python),
either fix PATH or run the site and API commands yourself with py -3.
git missing: install Git for Windows, restart the terminal, retry git --version.
Repository not found / 404: you are not in Tyneside-Software, or you cloned the old personal URL. Use:
https://github.com/Tyneside-Software/hackathon-site.git
https://github.com/Tyneside-Software/hackathon-api.gitHTTPS auth looping: sign in with a GitHub account that can see the org, or run gh auth login if you use GitHub CLI.
SSH Permission denied (publickey): either add your key to GitHub, or switch to the HTTPS clone URLs above.
The script expects ..\hackathon-api\app\main.py. That fails if the API was never cloned,
was renamed, or was cloned inside the site repo.
cd $env:USERPROFILE\source
Get-ChildItem
Test-Path .\hackathon-api\app\main.pyIf that is False, clone it there (do not nest it):
cd $env:USERPROFILE\source
git clone https://github.com/Tyneside-Software/hackathon-api.gitThen cd hackathon-site and run .\start.ps1 again.
PowerShell often opens in C:\Windows\System32. Cloning there is a mess.
Move the work to your profile and delete the accidental copy.
# see where you actually are
Get-Location
# if you already cloned in the wrong place, start clean:
mkdir $env:USERPROFILE\source -ErrorAction SilentlyContinue
cd $env:USERPROFILE\source
git clone https://github.com/Tyneside-Software/hackathon-site.git
git clone https://github.com/Tyneside-Software/hackathon-api.gitFolder names must be exactly hackathon-site and hackathon-api.
You probably still have a previous server window open. Close those two PowerShell windows first.
If that is not enough:
netstat -ano | findstr ":5500"
netstat -ano | findstr ":8080"Last column is the PID. Stop it:
taskkill /PID <pid> /FThen run .\start.ps1 again.
Activate.ps1 blocked: same as execution policy — fix that, then:
cd $env:USERPROFILE\source\hackathon-api
.\.venv\Scripts\Activate.ps1No module named uvicorn: the venv is missing or you ran uvicorn with system Python. Recreate:
cd $env:USERPROFILE\source\hackathon-api
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8080
Using the venv’s python.exe directly avoids activate entirely.
start.ps1 already does this once Python itself works.
Check you are on http://127.0.0.1:5500/, not file:// and not a random other port.
Stick to 127.0.0.1 or localhost consistently.
CORS in the API allow-list is http://127.0.0.1:5500 and http://localhost:5500.
Confirm the API process is up:
curl http://127.0.0.1:8080/health
For local work leave config.js as http://127.0.0.1:8080.
The live site uses the Cloud Run URL; CORS must allow
https://hackathon.tyneside.software as well as localhost.
Allow Python on private networks if Windows asks. You only need loopback — you are not hosting on the LAN.
If the tab spins, the server window usually has the real error (port in use, or Python missing).
The static server reads files from disk on each request. Hard-refresh the tab (Ctrl+F5).
If you opened file:// earlier, close that tab and go through http://127.0.0.1:5500/.
Set identity in this repo only (do not overwrite a teammate’s global config):
cd $env:USERPROFILE\source\hackathon-site
git config user.name "Your Name"
git config user.email "you@example.com"Push rejected because the remote branch moved (non-fast-forward):
git pull --rebase origin main
git push origin main
If you are on a feature branch, rebase that branch instead:
git pull --rebase origin reeve/onboarding-git then git push.
Do not force-push. Fix conflicts, keep the site loading, then push again.
First push of a new branch needs the upstream set. Use your actual branch name:
git push -u origin reeve/onboarding-gitAfter that, git push and git pull know which remote branch to use.
Do not reset if you have already pushed. Move the commits onto a branch, then restore main:
git branch reeve/rescue
git log origin/main..HEAD --oneline
git reset --hard origin/main
git checkout reeve/rescue
git push -u origin reeve/rescue
Only use reset --hard if you are sure those commits exist on reeve/rescue
and you have not mixed in other people’s unpublished work. Then merge the rescue branch as in step 11.
Git lists unmerged paths. Open each file, keep the correct content, remove conflict markers, then:
git add path\to\file
git status
git commit
git push
If you are mid-rebase and want to stop: git rebase --abort.
Mid-merge: git merge --abort. That returns you to the pre-merge state.
Refresh localhost after resolving. Home, Map, and Board must still load.
Commit what you want to keep, or stash the rest, then pull:
git status
git stash push -m "wip before pull"
git pull origin main
git stash popIf stash pop conflicts, fix files the same way as a merge conflict, then git add them.
git branch -d is refusing because those commits are not on main yet.
Merge first (step 11), then delete. To throw the branch away on purpose:
git branch -D reeve/onboarding-git — that drops the commits locally. Do not do this
if the work still matters.
That is expected tonight. Site-only serving is
py -3 -m http.server 5500 from hackathon-site.
The combined boot is .\start.ps1.