diff --git a/README.md b/README.md index 09fee18..3462444 100644 --- a/README.md +++ b/README.md @@ -137,52 +137,83 @@ npm run dev # start utviklingsserver på http://localhost:5173 Backend ligger i `backend/` og bruker PostgreSQL. GraphQL kommer i senere issues; foreløpig finnes migrasjon og seed for eksempelannonsene. -### Installasjon +| Miljø | Dokumentasjon | +| ---------------- | -------------------------------------------------------------------------------------------------------- | +| **Lokal maskin** | [Lokal backend-utvikling](#lokal-backend-utvikling) (under) | +| **NTNU-VM** | [docs/vm-backend.md](docs/vm-backend.md) — delt database, SSH, **ikke** samme som lokalt oppsett | +| systemd / Apache | [backend/deploy/README.md](backend/deploy/README.md), [deploy/apache/README.md](deploy/apache/README.md) | + +### Lokal backend-utvikling + +Følg dette for å kjøre migrasjon og seed på **egen PC**. VM-oppsettet er +separat og beskrives ikke her. + +**1. Node.js** — samme krav som frontend (se [Krav](#krav)): `nvm use` i +rotmappen (`.nvmrc` → Node 24). Sjekk med `node -v` og `npm -v`. + +**2. PostgreSQL lokalt** — installer PostgreSQL slik at du kan koble til +`localhost:5432` (Homebrew, apt, Postgres.app e.l.). Start tjenesten om den +ikke kjører. + +**3. Database og bruker** — opprett en database som matcher det du setter i +`.env` (eksempelnavn fra `backend/.env.example`: databasen `verktoyutlan`). +Passord settes interaktivt, ikke i shell-historikk: + +```bash +psql -h localhost -U postgres -d postgres +``` + +```sql +CREATE USER verktoyutlan_dev WITH LOGIN; +\password verktoyutlan_dev +CREATE DATABASE verktoyutlan OWNER verktoyutlan_dev; +\q +``` + +Tilpass bruker- og databasenavn etter eget valg; de må samsvare med `DATABASE_URL`. + +**4. Miljøfil** — fra repo-roten: ```bash cd backend -npm ci cp .env.example .env ``` -Rediger `.env` og sett `DATABASE_URL` til PostgreSQL-instansen du bruker -(lokalt eller på gruppens VM). Valgfritt: `PUBLIC_APP_BASE` styrer bildestier -i seed (standard `/project2`). +Rediger `backend/.env` og sett for eksempel: + +```env +DATABASE_URL=postgresql://verktoyutlan_dev:PASSORD@localhost:5432/verktoyutlan +``` -### Migrasjon og seed +(Erstatt `PASSORD` i filen — ikke skriv det i terminalkommandoer.) Filen skal +ikke committes. -Kjør migrasjon før seed, begge fra `backend/`: +**5. Avhengigheter, migrasjon og seed:** ```bash +npm ci +npm run typecheck npm run migrate npm run seed ``` -`npm run seed` er idempotent: eksisterende rader med samme `id` hoppes over -(`ON CONFLICT DO NOTHING`). Kjør seed på nytt uten duplikater. - -Seed fyller de 10 annonsene fra `src/data/mockListings.ts` (id `listing-001` til -`listing-010`). `image_url` lagres som offentlige stier under -`/project2/assets/listings/` (filnavn som i `src/assets/listings/`), uten at -backend importerer SVG-filer. - -**Bilder og deploy:** `npm run build` i frontend pakker SVG-ene inn i -JavaScript-bundelen. Den lager **ikke** løse filer på -`/project2/assets/listings/`. For at seedede URL-er skal fungere når klienten -senere leser fra databasen, må SVG-ene serveres **separat** på den stien, for -eksempel ved at Apache peker `/project2/assets/listings/` til en kopi av -`src/assets/listings/` på VM. Dette er ikke en del av Vite-bygget alene. +`npm run migrate` bruker `node-pg-migrate` og `.env`. `npm run seed` kjører +`src/scripts/seed.ts` og er idempotent (`ON CONFLICT DO NOTHING`). -### Verifisere data - -Etter migrasjon og seed: +**6. Verifisering:** ```bash -psql "$DATABASE_URL" -c "SELECT id, title, daily_price FROM listings ORDER BY id;" +npm run typecheck +psql -h localhost -U verktoyutlan_dev -d verktoyutlan -W -c "SELECT COUNT(*) FROM listings;" +npm run seed # forvent 0 nye annonser andre gang ``` -Forvent **10 rader**. Kjør `npm run seed` en gang til og sjekk at antall -fortsatt er 10. +Forvent **10** rader i `listings`. Seed-data tilsvarer +`src/data/mockListings.ts` (id `listing-001`–`listing-010`). + +**Bilder og deploy:** Seed lagrer `image_url` under `/project2/assets/listings/`. +Det gjelder VM/Apache senere — se [deploy/apache/README.md](deploy/apache/README.md). +Lokal frontend bruker fortsatt mock og importerte SVG-er. ## Kommandoer @@ -211,7 +242,10 @@ kontroller som er gjort i nettleser, står i [docs/testing.md](docs/testing.md). ## Mappestruktur ``` +deploy/ + apache/ Apache-vhost for /project2/ og /project2/api/ (mal) backend/ + deploy/ systemd-mal og VM-deploy (port 3001) migrations/ Versjonerte PostgreSQL-migrasjoner src/db/ Tilkoblingspool src/scripts/ Seed og andre engangsskript @@ -324,6 +358,8 @@ utlån, korte og lange titler, tomt tilbehør og annonser uten bilde. Se | [docs/prosjektstandard.md](docs/prosjektstandard.md) | Branches, commit-format, pull requests og krav før merge | | [docs/design.md](docs/design.md) | Farger, typografi, kontrast og felles komponenter | | [docs/testing.md](docs/testing.md) | Tester, kontroller, resultater og det som gjenstår | +| [docs/vm-backend.md](docs/vm-backend.md) | PostgreSQL og backend på NTNU-VM | +| [deploy/apache/README.md](deploy/apache/README.md) | Apache-mal for /project2/ og API-proxy | | [docs/ki-bruk.md](docs/ki-bruk.md) | Hvordan vi bruker og kontrollerer KI | `main` er beskyttet, så alt arbeid går via pull request mot `dev`. Maler for diff --git a/backend/deploy/README.md b/backend/deploy/README.md new file mode 100644 index 0000000..fcb6d5a --- /dev/null +++ b/backend/deploy/README.md @@ -0,0 +1,149 @@ +# Deploy: systemd og port 3001 (prosjekt 2) + +Mal for å kjøre GraphQL-backenden som egen systemd-tjeneste på +`it2810-36.idi.ntnu.no`. **Ikke aktiver på VM før GraphQL-server er implementert** +(se eget issue). Det finnes ingen HTTP-server i backend i dag — kun migrasjon, +seed og databasepool. + +## Avhengighet (GraphQL-issue) + +Før `systemctl enable --now` må repoet ha minst: + +- `backend/src/server.ts` (eller tilsvarende) som **leser `HOST` og `PORT` fra + miljø** og binder til **`127.0.0.1:3001`** (verdier fra + `/etc/t36-project2/backend.env` — ikke hardkode `0.0.0.0`). +- `npm ci` kjørt i `backend/`, slik at `node_modules/tsx/dist/cli.mjs` finnes. +- Valgfritt senere: `npm run build` + `ExecStart` mot `dist/server.js` i stedet + for tsx. + +`backend/package.json` har i dag **ikke** `start` — bare `migrate`, `seed` og +`typecheck`. + +## Filer + +| Fil | Formål | +| ------------------------------ | -------------------------------------------------------------------- | +| `t36-project2-backend.service` | systemd-enhet (`__DEPLOY_USER__`, `__BACKEND_DIR__`, `__NODE_BIN__`) | +| `backend.env.example` | Mal for `/etc/t36-project2/backend.env` | + +Migrasjon/seed kan fortsatt bruke `~/T36-Project-2/backend/.env`. Tjenesten leser +**kun** `/etc/t36-project2/backend.env` (utenfor git). + +## Plassholdere + +| Plassholder | Betydning | +| ----------------- | ---------------------------------------------------------------------- | +| `__DEPLOY_USER__` | NTNU-bruker på VM (ikke root) | +| `__BACKEND_DIR__` | Absolutt sti, f.eks. `/home//T36-Project-2/backend` | +| `__NODE_BIN__` | Full sti til Node 24, f.eks. output av `which node` etter `nvm use 24` | + +## Forberedelse på VM (etter GraphQL er merget) + +Erstatt `` med faktisk bruker (samme som eier repoet). + +```bash +export DEPLOY_USER="" +export BACKEND_DIR="/home/${DEPLOY_USER}/T36-Project-2/backend" + +cd "${BACKEND_DIR}/.." +git pull +cd "${BACKEND_DIR}" +nvm use 24 +npm ci +npm run typecheck +test -f node_modules/tsx/dist/cli.mjs +# npm run build — hvis dere bytter ExecStart til dist/server.js +``` + +Noter Node-sti: + +```bash +export NODE_BIN="$(which node)" +echo "${NODE_BIN}" +``` + +## Miljøfil utenfor git + +Tjenesten kjører som **`DEPLOY_USER`** ( ikke root ). Filen skal være lesbar for +prosessen, men ikke for «alle» på VM: + +```bash +export DEPLOY_USER="" + +sudo mkdir -p /etc/t36-project2 +sudo cp "/home/${DEPLOY_USER}/T36-Project-2/backend/deploy/backend.env.example" \ + /etc/t36-project2/backend.env +sudo nano /etc/t36-project2/backend.env # DATABASE_URL, HOST, PORT +sudo chmod 640 /etc/t36-project2/backend.env +sudo chown "root:${DEPLOY_USER}" /etc/t36-project2/backend.env +``` + +**Krav i filen:** `HOST=127.0.0.1`, `PORT=3001`. GraphQL-implementasjonen må respektere +disse. + +## Installere tjenesten (manuelt, én gang) + +Kjør på VM etter `nvm use 24` og `npm ci` i backend: + +```bash +export DEPLOY_USER="" +export BACKEND_DIR="/home/${DEPLOY_USER}/T36-Project-2/backend" +export NODE_BIN="$(which node)" + +sed -e "s|__DEPLOY_USER__|${DEPLOY_USER}|g" \ + -e "s|__BACKEND_DIR__|${BACKEND_DIR}|g" \ + -e "s|__NODE_BIN__|${NODE_BIN}|g" \ + "${BACKEND_DIR}/deploy/t36-project2-backend.service" \ + | sudo tee /etc/systemd/system/t36-project2-backend.service > /dev/null + +sudo systemctl daemon-reload +``` + +**Ikke kjør `enable` eller `start` før `src/server.ts` finnes** og du har testet: + +```bash +"${NODE_BIN}" "${BACKEND_DIR}/node_modules/tsx/dist/cli.mjs" "${BACKEND_DIR}/src/server.ts" +``` + +Når GraphQL er klar: + +```bash +sudo systemctl enable t36-project2-backend +sudo systemctl start t36-project2-backend +``` + +## Kontroll + +```bash +sudo systemctl status t36-project2-backend +sudo systemctl is-enabled t36-project2-backend +journalctl -u t36-project2-backend -n 50 --no-pager +curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3001/ +sudo ss -tlnp | grep 3001 +``` + +Stopp / restart: + +```bash +sudo systemctl stop t36-project2-backend +sudo systemctl restart t36-project2-backend +``` + +Ved OS-omstart: autostart når enheten er **enabled** (`Restart=on-failure` ved krasj). + +## Prosjekt 1 + +- Enheten heter `t36-project2-backend` og bruker port **3001** — ikke endre + prosjekt 1s tjenester eller Apache-vhosts. + +## Oppdatere etter pull + +```bash +export BACKEND_DIR="/home//T36-Project-2/backend" +cd "${BACKEND_DIR}" && npm ci +sudo systemctl restart t36-project2-backend +``` + +Ved bytt til produksjonsbuild, oppdater `ExecStart` i +`/etc/systemd/system/t36-project2-backend.service` (f.eks. `node dist/server.js`), +deretter `daemon-reload` og `restart`. diff --git a/backend/deploy/backend.env.example b/backend/deploy/backend.env.example new file mode 100644 index 0000000..b6a973a --- /dev/null +++ b/backend/deploy/backend.env.example @@ -0,0 +1,21 @@ +# Eksempel for systemd-tjenesten på VM. +# Kopier til /etc/t36-project2/backend.env (aldri commit med passord). +# +# sudo mkdir -p /etc/t36-project2 +# sudo cp backend/deploy/backend.env.example /etc/t36-project2/backend.env +# sudo chmod 640 /etc/t36-project2/backend.env +# sudo chown root:__DEPLOY_USER__ /etc/t36-project2/backend.env +# +# Tjenesten kjører som __DEPLOY_USER__ (ikke root). Med 640 og gruppe = +# deploy-brukeren kan prosessen lese filen; andre brukere på VM kan ikke. + +DATABASE_URL=postgresql://t36_project2:PASSORD@localhost:5432/t36_project2 + +# Krav til kommende GraphQL-server (eget issue): les HOST og PORT, lytt kun på +# 127.0.0.1 — ikke 0.0.0.0. Apache proxyer senere mot http://127.0.0.1:3001. +HOST=127.0.0.1 +PORT=3001 +NODE_ENV=production + +# Valgfritt: offentlig rot for seed-bilder +# PUBLIC_APP_BASE=/project2 diff --git a/backend/deploy/t36-project2-backend.service b/backend/deploy/t36-project2-backend.service new file mode 100644 index 0000000..7673db0 --- /dev/null +++ b/backend/deploy/t36-project2-backend.service @@ -0,0 +1,33 @@ +# Mal for gruppens Ubuntu-VM. GraphQL-serveren finnes ikke ennå — ikke enable +# tjenesten før src/server.ts (eller tilsvarende) og npm run start er på plass. +# +# Installasjon: se backend/deploy/README.md (erstatt __DEPLOY_USER__, __BACKEND_DIR__, +# __NODE_BIN__). + +[Unit] +Description=T36 Project 2 backend (GraphQL, port 3001) +Documentation=file://__BACKEND_DIR__/deploy/README.md +After=network-online.target postgresql.service +Wants=network-online.target +# Prosjekt 2 egen enhet — ikke delt med prosjekt 1 + +[Service] +Type=simple +User=__DEPLOY_USER__ +Group=__DEPLOY_USER__ +WorkingDirectory=__BACKEND_DIR__ + +# Hemmeligheter utenfor git (DATABASE_URL, HOST, PORT, osv.) +EnvironmentFile=/etc/t36-project2/backend.env + +# Node 24 (nvm) + tsx fra backend/node_modules etter «npm ci» — ikke global tsx +ExecStart=__NODE_BIN__ __BACKEND_DIR__/node_modules/tsx/dist/cli.mjs __BACKEND_DIR__/src/server.ts + +Restart=on-failure +RestartSec=5 +TimeoutStopSec=30 + +NoNewPrivileges=true + +[Install] +WantedBy=multi-user.target diff --git a/deploy/apache/README.md b/deploy/apache/README.md new file mode 100644 index 0000000..8f54dcf --- /dev/null +++ b/deploy/apache/README.md @@ -0,0 +1,148 @@ +# Apache: frontend `/project2/` og API-proxy + +Mal for å serve prosjekt 2 på gruppens VM **uten** å endre prosjekt 1s +Apache-oppsett. **Ikke aktiver på VM ennå** — krever bygget frontend med riktig +`base`, og GraphQL på port 3001. + +## Vite: base path og statiske filer + +| Tema | Status i repo nå | Krav ved VM-deploy | +| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `base` | Standard `/` i `vite.config.ts` | Sett `base: '/project2/'` i eget frontend-issue før produksjonsbuild | +| React Router | `basename={import.meta.env.BASE_URL}` i `main.tsx` | Følger automatisk Vite `base` | +| JS/CSS fra build | Hashede filer under `dist/assets/` | URL-er blir `/project2/assets/…` når `base` er satt | +| SVG i mock | Importert i bundle | Fungerer i dagens prototype | +| SVG i seed (`image_url`) | `/project2/assets/listings/*.svg` | **Ikke** fra Vite-build — egen Apache-`Alias` i `t36-project2.conf` mot `src/assets/listings/` | + +Bygg (etter `base` er satt): + +```bash +cd __REPO_ROOT__ +nvm use 24 +npm ci +npm run build +# deploy __DIST_DIR__ (typisk __REPO_ROOT__/dist) +``` + +Test lokalt med base uten Apache: + +```bash +npm run preview -- --base /project2/ +``` + +## Apache-moduler (Ubuntu `apache2`) + +Konfigurasjonen forutsetter at modulene er **enabled**. Sjekk: + +```bash +apache2ctl -M | grep -E 'alias_module|rewrite_module|proxy_module|proxy_http_module' +``` + +Aktiver manglende moduler (krever sudo; **ikke** deaktiver prosjekt 1): + +```bash +sudo a2enmod alias rewrite proxy proxy_http +``` + +Valgfritt senere: `headers` for cache på statiske filer. + +## Filer + +| Fil | Formål | +| ------------------- | -------------------------------------------------- | +| `t36-project2.conf` | Egen site: statisk SPA, listing-SVG, reverse proxy | + +Plassholdere: + +| Plassholder | Eksempel | +| --------------- | -------------------------------------------- | +| `__REPO_ROOT__` | `/home//T36-Project-2` | +| `__DIST_DIR__` | `/home//T36-Project-2/dist` | + +## Reverse proxy og GraphQL + +| Klient (nettleser) | Backend (Node på VM) | +| -------------------------------- | ------------------------------- | +| `https://…/project2/api/graphql` | `http://127.0.0.1:3001/graphql` | + +`ProxyPass /project2/api/` fjerner ikke `/project2/api` i stien mot backend — +mappingen er: + +- Forespørsel: `/project2/api/graphql` +- Backend mottar: `/graphql` (prefiks `/project2/api/` → rot på 3001) + +GraphQL-implementasjonen bør eksponere f.eks. `POST /graphql` på port 3001. +Apollo Client konfigureres senere med URL under `/project2/api/`. + +Backend må fortsatt lytte på **`127.0.0.1:3001`** (systemd), ikke på `0.0.0.0`. + +## SPA-ruter + +Uten `mod_rewrite` vil direkte navigering til f.eks. `/project2/annonser/listing-001` +gi 404 fra Apache. `RewriteRule` i `t36-project2.conf` sender ukjente stier til +`/project2/index.html` når fil/mappe ikke finnes. + +## Listing-SVG (seed) + +Seed lagrer `image_url` som `/project2/assets/listings/drill.svg` osv. +**Mer spesifikk** `Alias` for `/project2/assets/listings` kommer **før** generell +`Alias /project2`, slik at SVG ikke overskygges av SPA-fallback. + +Filene ligger i repo: `src/assets/listings/*.svg` (samme navn som i seed). + +## Installasjon på VM (når klart — ikke kjør enable før dere er klare) + +Forutsetter: prosjekt 1 fungerer; dere har testet `npm run build` med +`base: '/project2/'`; GraphQL kjører på 3001 (senere). + +```bash +export DEPLOY_USER="" +export REPO_ROOT="/home/${DEPLOY_USER}/T36-Project-2" +export DIST_DIR="${REPO_ROOT}/dist" + +sudo a2enmod alias rewrite proxy proxy_http + +sed -e "s|__REPO_ROOT__|${REPO_ROOT}|g" \ + -e "s|__DIST_DIR__|${DIST_DIR}|g" \ + "${REPO_ROOT}/deploy/apache/t36-project2.conf" \ + | sudo tee /etc/apache2/sites-available/t36-project2.conf > /dev/null + +# Valider FØR reload — skal vise «Syntax OK» +sudo apache2ctl configtest + +# Først når configtest er OK og dere har avtalt med gruppen: +# sudo a2ensite t36-project2.conf +# sudo systemctl reload apache2 +``` + +**Ikke** `a2dissite` på prosjekt 1 eller rediger deres vhost-filer. + +## Kontroll etter aktivering + +```bash +sudo apache2ctl -S +curl -I "https://it2810-36.idi.ntnu.no/project2/" +curl -I "https://it2810-36.idi.ntnu.no/project2/assets/listings/drill.svg" +curl -sS -o /dev/null -w "%{http_code}\n" -X POST \ + "https://it2810-36.idi.ntnu.no/project2/api/graphql" \ + -H "Content-Type: application/json" -d '{"query":"{ __typename }"}' +``` + +SPA: åpne `/project2/annonser/listing-001` i nettleser og trykk refresh — skal +ikke gi Apache 404. + +## Avhengigheter + +1. Frontend-issue: `base: '/project2/'` i `vite.config.ts` + produksjonsbuild. +2. GraphQL-issue: server på `127.0.0.1:3001`, endepunkt `/graphql` (eller dokumentert sti). +3. systemd: `t36-project2-backend` enabled (se `backend/deploy/README.md`). + +## Feilsøking + +| Symptom | Mulig årsak | +| ---------------------------------- | --------------------------------------------------- | +| `configtest` feiler på `ProxyPass` | `proxy` / `proxy_http` ikke enabled | +| SPA 404 ved refresh | `rewrite` ikke enabled, eller feil `RewriteBase` | +| SVG 404 | Feil `__REPO_ROOT__`, eller listing-`Alias` mangler | +| API 502/503 | Backend ikke startet på 3001 | +| `/project2` ødelegger P1 | Feil site aktivert — bruk kun `t36-project2.conf` | diff --git a/deploy/apache/t36-project2.conf b/deploy/apache/t36-project2.conf new file mode 100644 index 0000000..ade35a8 --- /dev/null +++ b/deploy/apache/t36-project2.conf @@ -0,0 +1,48 @@ +# Prosjekt 2 (T36) — egen Apache-site. Publiseres som +# /etc/apache2/sites-available/t36-project2.conf +# +# Erstatt plassholdere ved installasjon (se deploy/apache/README.md): +# __REPO_ROOT__ — f.eks. /home//T36-Project-2 +# __DIST_DIR__ — f.eks. __REPO_ROOT__/dist (etter npm run build med base /project2/) +# +# Ikke rediger prosjekt 1s vhost. Aktiver med a2ensite t36-project2.conf. + +# Seed/API-bilder: løse SVG-er (Vite bygger dem ikke ut til denne stien) + + Alias /project2/assets/listings __REPO_ROOT__/src/assets/listings + + + + Require all granted + Options -Indexes + + +# Frontend (Vite build med base: '/project2/') + + Alias /project2 __DIST_DIR__ + + + + Require all granted + Options -Indexes +FollowSymLinks + AllowOverride None + + # SPA: direkte URL og refresh (React Router) + + RewriteEngine On + RewriteBase /project2/ + RewriteRule ^index\.html$ - [L] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteCond %{REQUEST_FILENAME} !-d + RewriteRule . /project2/index.html [L] + + + +# GraphQL-backend (127.0.0.1:3001) — /project2/api/graphql → backend /graphql + + + ProxyPreserveHost On + ProxyPass /project2/api/ http://127.0.0.1:3001/ + ProxyPassReverse /project2/api/ http://127.0.0.1:3001/ + + diff --git a/docs/ki-bruk.md b/docs/ki-bruk.md index f86081a..0e5957d 100644 --- a/docs/ki-bruk.md +++ b/docs/ki-bruk.md @@ -2,39 +2,34 @@ ## Verktøy - | Verktøy | Modell | Brukes til | | ----------- | --------------- | -------------------------------------------------- | | Claude Code | Claude Opus 5.5 | Planlegging, issues, kode, tester og dokumentasjon | - ## Slik bruker vi KI - KI får en avgrenset oppgave, normalt ett issue med akseptansekriterier. - KI skriver kode i samme stil som resten av repoet og bruker de felles -komponentene, typene og hjelpefunksjonene. + komponentene, typene og hjelpefunksjonene. - Alt KI lager, går gjennom vanlig pull request og må godkjennes av et -gruppemedlem før merge, på samme måte som annen kode. - - + gruppemedlem før merge, på samme måte som annen kode. ## Slik kontrollerer vi resultatene 1. **Automatiske kontroller:** typecheck, lint, format:check, test og build - må gå uten feil. + må gå uten feil. 2. **Nettleser:** endringen prøves i appen, også på smal skjerm og med - tastatur. + tastatur. 3. **Akseptansekriterier:** hvert kriterium i issuet sjekkes mot det som er - laget. + laget. 4. **Gjennomgang i pull request:** et annet gruppemedlem leser koden og kan be - om endringer. + om endringer. Feil som KI har gjort og som blir oppdaget, føres i loggen under, slik at vi ser hva vi bør være oppmerksomme på. ## Logg - | Issue | Hva KI gjorde | Kontroll og funn | | ----- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | – | Gikk gjennom repoet mot arbeidsplanen og foreslo de resterende issuene til innlevering 1 | Issuene ble lest og opprettet av gruppen | @@ -45,5 +40,4 @@ ser hva vi bør være oppmerksomme på. | #3 | Skrev prosjektstandard, maler for issues og pull requests og dette dokumentet | Standarden ble sjekket mot commit-historikken og reglene i repoet | | #21 | Kjørte sluttkontrollen før innlevering 1 og rettet det den fant | Fant at `engines` tillot Node-versjoner som `jsdom` ikke støtter, og at favicon manglet. Begge er rettet. PR-er, review og merge til `main` gjøres av gruppen | | #31 | Kjørte en kontroll på backend oppsettet | Sluttkontroll fant Prettier-feil og at seed-bilder ikke følger av Vite-build; dokumentasjon oppdatert. Migrate/seed og typecheck verifisert. PR og merge gjøres av gruppen | - - +| #33 | Kontroll på oppsettet av backend i VM | Maler er ikke aktivert på VM. GraphQL og Vite `base` gjenstår. SSH til VM ble kjørt manuelt. PR og merge gjøres av gruppen | diff --git a/docs/vm-backend.md b/docs/vm-backend.md new file mode 100644 index 0000000..17483bc --- /dev/null +++ b/docs/vm-backend.md @@ -0,0 +1,241 @@ +# VM: PostgreSQL og backend (prosjekt 2) + +Kort beskrivelse av databaselaget på gruppens NTNU-VM. **GraphQL, Apache og +backend-server på port 3001 er ikke satt opp ennå** — det kommer i senere issues. + +**Lokal utvikling på egen maskin** (egen PostgreSQL, egen `.env`) står i +README under [Lokal backend-utvikling](../README.md#lokal-backend-utvikling). +Dette dokumentet gjelder **kun** den delte VM-en. + +**VM:** `it2810-36.idi.ntnu.no` (Ubuntu 26.04.1 LTS) + +## Status på VM (verifisert) + +Følgende er **allerede på plass** og testet: + +| Komponent | Detalj | +| -------------- | ------------------------------------------------------ | +| PostgreSQL | 18.6, cluster `18/main`, port 5432, autostart | +| Database | `t36_project2` | +| Databasebruker | `t36_project2` | +| Node.js | 24.21.0 via nvm (npm 11.x) | +| Schema/data | `npm run migrate` og seed med 10 annonser i `listings` | + +Repo for prosjekt 2 ligger typisk i `~/T36-Project-2` på VM. + +**Andre gruppemedlemmer** trenger normalt bare NTNU VPN, SSH-tilgang til VM-en og +`DATABASE_URL` (databasepassord) etter avtale med gruppen. De skal **ikke** kjøre +førstegangsoppsettet under med mindre noe må bygges på nytt. + +## 1. SSH via NTNU VPN + +1. Koble til [NTNU VPN](https://i.ntnu.no/vpn). +2. Logg inn (bytt ut brukernavn med ditt NTNU-brukernavn): + +```bash +ssh @it2810-36.idi.ntnu.no +``` + +Passord eller SSH-nøkkel avhenger av VM-oppsettet fra faget. + +## 2. Repo og backend (vanlig flyt) + +### Første gang på VM + +```bash +cd ~ +git clone https://git.ntnu.no/IT2810-H26/T36-Project-2.git +cd T36-Project-2 +git checkout dev +git pull +``` + +### Senere besøk + +```bash +cd ~/T36-Project-2 +git pull +``` + +### Avhengigheter, migrasjon og seed + +Alle kommandoer under kjøres fra **`~/T36-Project-2/backend`**: + +```bash +cd ~/T36-Project-2/backend +nvm use 24 # eller tilsvarende, slik at node -v viser 24.x +npm ci +npm run typecheck +npm run migrate +npm run seed +``` + +- Første seed på tom database: forvent **10 nye** annonser. +- Senere kjøringer: **0 nye**, 10 hoppet over (idempotent). + +## 3. Sikker håndtering av `DATABASE_URL` + +- **`DATABASE_URL` skal aldri committes.** Kun `backend/.env.example` med + plassholdere ligger i git. +- På VM: opprett `backend/.env` (fra `.env.example`), fyll inn verdi gruppen har + avtalt, og begrens filrettigheter — **fra katalogen `backend/`**: + +```bash +cd ~/T36-Project-2/backend +cp .env.example .env +# Rediger .env i editor (ikke lim passord inn i terminalkommandoer) +chmod 600 .env +``` + +- Eksempelformat i `.env` (erstatt passord med gruppen sitt, ikke skriv det i + dokumentasjon eller issues): + +```env +DATABASE_URL=postgresql://t36_project2:PASSORD@localhost:5432/t36_project2 +``` + +Erstatt `PASSORD` i editoren med gruppen sitt databasepassord (ikke i terminal +eller git). Alternativt kan gruppen senere vurdere +[pgpass](https://www.postgresql.org/docs/current/libpq-pgpass.html) om gruppen +velger det senere. + +- **Ikke** eksporter `DATABASE_URL` i shell med passord i klartekst (historikk). + `npm run migrate` og `npm run seed` leser `.env` via `--envPath` / `--env-file`. + +## 4. Kontroll at oppsettet fungerer + +Fra **`~/T36-Project-2/backend`**: + +```bash +npm run typecheck +npm run migrate # forvent «No migrations to run!» når schema er oppdatert +npm run seed # forvent 0 nye når data allerede finnes +``` + +SQL (passord **interaktivt**, ikke i kommandolinjen): + +```bash +psql -h localhost -U t36_project2 -d t36_project2 -W -c "SELECT COUNT(*) FROM listings;" +psql -h localhost -U t36_project2 -d t36_project2 -W -c "SELECT id, title, daily_price FROM listings ORDER BY id;" +``` + +Forvent **10** rader i `listings`. + +Tjenester og Node: + +```bash +sudo systemctl is-active postgresql +node -v +``` + +## 5. Prosjekt 1 på samme VM + +- **Ikke** stopp, avinstaller eller rekonfigurer Apache, databaser eller tjenester + som prosjekt 1 bruker uten å sjekke med gruppen. +- Prosjekt 2 bruker egen database (`t36_project2`) — ikke del eller overskriv + prosjekt 1s data. +- Apache `/project2` og port **3001** er **ikke** konfigurert for prosjekt 2 ennå. + +Etter fremtidige endringer: verifiser at prosjekt 1 fortsatt fungerer. + +## 6. Backup + +VM-en har **ikke** automatisk backup. Ved behov, fra **`~/T36-Project-2/backend`** +(passord via `-W`): + +```bash +pg_dump -h localhost -U t36_project2 -d t36_project2 -Fc -W -f "t36_project2-$(date +%Y%m%d).dump" +``` + +Lagre dump utenfor VM. Gjenoppretting er gruppens ansvar. + +--- + +## Referanse: førstegangsoppsett på VM + +> **Kun ved ny VM eller gjenoppbygging.** Gruppemedlemmer som kobler til +> eksisterende VM skal **ikke** kjøre dette på nytt uten avtale. + +### PostgreSQL: installasjon og tjeneste + +```bash +sudo apt update +sudo apt install -y postgresql postgresql-contrib +sudo systemctl enable postgresql +sudo systemctl start postgresql +pg_lsclusters +``` + +### Database og bruker (passord interaktivt) + +Ikke endre databaser som tilhører prosjekt 1. + +```bash +sudo -u postgres psql +``` + +I `psql`: + +```sql +CREATE USER t36_project2; +CREATE DATABASE t36_project2 OWNER t36_project2; +GRANT ALL PRIVILEGES ON DATABASE t36_project2 TO t36_project2; +\password t36_project2 +\q +``` + +Test ( `-W` ber om passord): + +```bash +psql -h localhost -U t36_project2 -d t36_project2 -W -c 'SELECT 1 AS ok;' +``` + +### Node.js 24 via nvm + +Prosjektet krever Node 22.22.2+ eller 24.15+ (se `.nvmrc`). + +Installer nvm etter [nvm-dokumentasjonen](https://github.com/nvm-sh/nvm), logg ut +og inn, deretter: + +```bash +nvm install 24 +nvm use 24 +node -v +``` + +## 7. systemd og port 3001 (forberedt i repo) + +Mal for egen systemd-tjeneste ligger i +[backend/deploy/README.md](../backend/deploy/README.md): + +- `backend/deploy/t36-project2-backend.service` — egen enhet for prosjekt 2 +- `backend/deploy/backend.env.example` — miljøvariabler under + `/etc/t36-project2/backend.env` (utenfor git) + +Tjenesten kjører som **ikke-privilegert** NTNU-bruker, leser +`/etc/t36-project2/backend.env` (`chmod 640`, eier `root:`). GraphQL må +**binde til `HOST=127.0.0.1` og `PORT=3001`** fra den filen. **Ikke `enable`/`start` +på VM ennå** — `src/server.ts` mangler; `ExecStart` bruker Node + lokal +`node_modules/tsx` etter `npm ci`. + +## 8. Apache `/project2/` (forberedt i repo) + +Egen site-mal (prosjekt 2 only) ligger i +[deploy/apache/README.md](../deploy/apache/README.md): + +- Statisk frontend fra `dist/` med SPA-fallback +- `Alias` for listing-SVG under `/project2/assets/listings/` +- Reverse proxy `/project2/api/` → `http://127.0.0.1:3001/` + +Krever `a2enmod alias rewrite proxy proxy_http` og **`apache2ctl configtest`** +før `reload`. **Ikke `a2ensite` på VM ennå** — krever Vite `base: '/project2/'` +og GraphQL. + +## Gjenstår (ikke implementert) + +- GraphQL-server som faktisk kan startes av systemd +- Aktivering av `t36-project2-backend` på VM +- Aktivering av Apache-site `t36-project2.conf` +- Frontend koblet til API + +Se [README](../README.md) for planlagt videre arbeid.