From 7fc6c3f313d55c518df840ddac3d5fbc066d4d9b Mon Sep 17 00:00:00 2001 From: malinnsnieske Date: Tue, 10 Dec 2024 13:57:46 +0100 Subject: [PATCH] update readme (#541) * update readme --------- Co-authored-by: Mailn Nifeli Snieske --- README.md | 145 +++++++++++++++++++++++++++++---- backend/README.md | 96 ---------------------- frontend/beCompliant/README.md | 133 ------------------------------ 3 files changed, 131 insertions(+), 243 deletions(-) delete mode 100644 backend/README.md delete mode 100644 frontend/beCompliant/README.md diff --git a/README.md b/README.md index 44e70eea8..98805d8e4 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,136 @@ -# spire-kk +# Kartverket - Regelrett -Spire: Kartverket - regelrett* +Velkommen til Regelrett! -Solution for receiving information from several views/tables in Airtable and present it in a GUI. -Provides a user interface which allows the user to insert and update answers to the questions to a PostGresQl Database. +Denne applikasjonen er bygget for visning av data i tabellformat på en oversiktlig og brukervennlig måte. Løsningen støtter for øyeblikket +data fra AirTable og YAML-filer. Den er utviklet med fokus på å hjelpe brukere med å oppfylle krav og standarder ved å gi +en strukturert oversikt over nødvendige data. Brukere kan legge inn svar i ulike formater samt legge til kommentarer +direkte i tabellens rader, noe som gjør det enkelt å holde oversikt over status og nødvendig informasjon. Løsningen er +fleksibel og tilrettelagt for videre utvidelser etter behov. -See README.md in backend and frontend directories for setup +Følg stegene nedenfor for å komme i gang, og bruk de tilgjengelige skriptene for å administrere prosjektet effektivt. -## How to run using docker +## Sette opp database lokalt +### Steg 1 +Start med å klone repoet fra GitHub: -1. Clone the github repository -2. Follow these steps in the backend - readme [Add airtable token](https://github.com/bekk/spire-kk/blob/main/backend/README.md#add-airtable-token) - and [Local Postgres](https://github.com/bekk/spire-kk/tree/main/backend#local-postgres) -3. In compose.yaml change the environment variable `DB_USER` to the username that is given when initializing the - database cluster in the previous step. -4. Run in the root folder `docker compose up` -5. To stop the docker container run `docker compose down` +`git clone ` + +### Steg 2 +For å sette opp databasen må man ha installert Docker. Dette kan du gjøre ved å kjøre denne kommandoen: + +`brew cask install docker` + +### Steg 3 +Du trenger også et verktøy for håndtering av containere eller et container-runtime miljø som lar deg kjøre containere på din lokale maskin. +Du kan bruker docker desktop dersom du har det. Hvis ikke kan du bruke Colima. Last ned Colima ved å kjøre denne kommandoen: + +`brew install colima`. + +### Steg 4 +Etter å ha installert Colima, kan du starte det opp ved å kjøre denne kommandoen: + +`colima start` + +### Steg 5 +Når du har Colima eller Docker Desktop kjørende, kjør denne kommandoen: + +`docker run --name regelrett-db -it -e POSTGRES_PASSWORD=pwd -e POSTGRES_USER=postgres -e POSTGRES_DB=regelrett -p 5432:5432 -d postgres:15.4` + +Nå skal databasen være oppe og kjøre! + +### Steg 6 +Kjør denne kommandoen for å migrere databaseskjemaer som ligger i resources/db.migration: + +`./gradlew flywayMigrate` + +### Info +- Filen curl.txt inneholder curl kommandoer for å utføre spørringer mot Airtable +- Applikasjonen bruker en PostgresQl Database, og Flyway migration for å gjøre endringer på databaseskjemaer. +- Alle filer i Flyway migration script må ha følgende format: + +`__.sql` For eksempel: `V1.1__initial.sql` + +- Databasen heter "regelrett", og må foreløpig settes opp lokalt på utviklerens maskin utenfor Flyway. +- Databasemigreringer kjører automatisk ved oppstart av applikasjonen, eller så kan de kjøres manuelt med `./gradlew flywayMigrate` + + +## Kjøre backend lokalt + +### Steg 1 +- Gå inn på `Run -> Edit configurations` +- Trykk på + for å legge til ny konfigurasjon og velg KTOR +- Sett `no.bekk.ApplicationKt` som main class + +### Steg 2 +Du trenger å sette følgende miljøvariabler: +``` +AIRTABLE_ACCESS_TOKEN +CLIENT_ID +CLIENT_SECRET +TENANT_ID +``` +For å få tilgang til hemmelighetene, spør noen på teamet om å gi deg tilgang til 1Password vaulten. + +`AIRTABLE_ACCESS_TOKEN` er lagret under `AirTable` i vaulten, og `CLIENT_ID`, `CLIENT_SECRET` +og `TENANT_ID` er lagret under `EntraId`. + +Du kan sette miljøvariablene i IntelliJ ved å gå inn på `Run -> Edit configurations`. + +### Steg 3 +Du skal nå kunne kjøre backend, gå inn på http://localhost:8080 + +### Mer dokumentasjon +For mer dokumentasjon om [build and deployment](./docs/build-and-deployment.md), [kodestruktur](./docs/code-structure.md) og +[datamodell](./docs/data-model.md) se /docs mappen. + + +## Kjøre frontend lokalt +Frontend er bygget med React, Vite og TypeScript. + +### Steg 1 +Før du begynner, sørg for at du har følgende installert: + +- **[Node.js](https://nodejs.org)** (versjon 14.x eller nyere) +- **[npm](https://www.npmjs.com/get-npm)** + +### Steg 2 +Gå inn i frontend mappen: + +`cd /frontend/beCompliant` + +### Steg 3 +Installer avhengigheter ved å kjøre: + +`npm install` + +### Steg 4 +Forbered Husky (hvis aktuelt) ved å kjøre: + +`npm run prepare` + +### Steg 5 +Start utviklingsserveren ved å kjøre: + +`npm run dev` + +Dette vil starte Vite utviklingsserveren, og du kan se appen på http://localhost:3000. + +### Mer informasjon +- For å sikre kodekvalitet, kjør lint-verktøyet: `npm run lint` +- For å automatisk fikse lintingproblemer: `npm run lint-fix` +- For å formatere kodebasen med Prettier: `npm run format`. Dette vil formatere alle filer i src-mappen +- For å lage en produksjonsklar versjon av prosjektet: `npm run build`. Dette vil kompilere TypeScript-filene og +pakke applikasjonen ved hjelp av Vite. Output vil bli plassert i dist-mappen, klar for utrulling. +- Før du ruller ut, kan du forhåndsvise produksjonsbygget lokalt: `npm run preview`. Denne kommandoen vil servere +produksjonsbygget på en lokal server, slik at du kan verifisere at alt fungerer som forventet. +- Husky er konfigurert til å kjøre visse skript før commits blir fullført. Dette inkluderer linting og TypeScript-sjekker +for å sikre kodekvalitet og konsistens. For å manuelt utløse disse sjekkene, kan du kjøre: `npm run pre-commit`. +Dette vil kjøre lint-staged for å sjekke de stage’ede filene og sikre at TypeScript-filene er feilfrie før de blir +committet. +- Dette prosjektet bruker TanStack Query (tidligere kjent som React Query) for å håndtere nettverksforespørsler og +servertilstand. TanStack Query forenkler datainnhenting, caching, synkronisering og oppdatering av servertilstand i +React-applikasjoner. Ved å bruke dette kraftige biblioteket sikrer prosjektet effektiv og pålitelig datahåndtering, +minimerer unødvendige nettverksforespørsler, og gir en optimal brukeropplevelse med automatiske bakgrunnsoppdateringer +og feilhåndtering. Se dokumentasjonen for Tanstack Query her https://tanstack.com/query/latest +- For mer dokumentasjon om [Build and deployment](./docs/build-and-deployment.md) \ No newline at end of file diff --git a/backend/README.md b/backend/README.md deleted file mode 100644 index 5e64b9b9b..000000000 --- a/backend/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Local database (postgres) - -To setup the database you need docker installed - -``` -brew cask install docker -``` - -You also need a container management tool or container runtime environments that allow you to run containers on your -local machine. - -If you have docker desktop you can use that. - -Otherwise you can use Colima - -``` -brew install colima -``` - -after installation has finished start colima by running - -``` -colima start -``` - -once you have colima or docker desktop running run the following command - -``` -docker run --name regelrett-db -it -e POSTGRES_PASSWORD=pwd -e POSTGRES_USER=postgres -e POSTGRES_DB=regelrett -p 5432:5432 -d postgres:15.4 -``` - -You should now have a working database up and running - -Run `./gradlew flywayMigrate` to migrate the DB Schemas in resources/db.migration - -# How to run locally - -You need to set the following environment variables: -``` -AIRTABLE_ACCESS_TOKEN -CLIENT_ID -CLIENT_SECRET -TENANT_ID -``` - -To get access to the secrets ask someone on the team to give you access to the 1password vault. -`AIRTABLE_ACCESS_TOKEN` is stored under the name `AirTable` in the vault and `CLIENT_ID`, `CLIENT_SECRET` -and `TENANT_ID` is stored under `EntraId`. - -You can do this in IntelliJ under `Run -> Edit configurations`. Most of the values can be found in 1Password. You should be given access by another team member. - -## Build with Gradle - -gradle build - -## Run in IntelliJ - -Edit Configurations -> Set up Runtime Environment with KTOR, and point to the class Application.kt - -Set up as follows: - -Working directory: /backend -Use classpath of module: spire-kk.backend.main - -## Run the application - -To set up an IntelliJ project, New Project from existing sources -> -> Gradle project - -# curl.txt - -Contains curl commands for querying Airtable - -# Flyway - -The Application uses a PostgresQl Database, and Flyway migration to modify the database schema. - -Each file in the Flyway migration script has to have the following format: - -__.sql - -example: - -`V1.1__initial.sql` - -The database name is "regelrett", and right now it has to be setup locally on the developers PC outside of Flyway. -Database migrations are run automatically on application startup. Or you can run them manually with `./gradlew flywayMigrate` - -# More documentation - -For more documentation -about [Build and deployment](./docs/build-and-deployment.md) [code structure](./docs/code-structure.md) and -the [data model](./docs/data-model.md) check -out the /docs directory. - - diff --git a/frontend/beCompliant/README.md b/frontend/beCompliant/README.md deleted file mode 100644 index bcca5d72a..000000000 --- a/frontend/beCompliant/README.md +++ /dev/null @@ -1,133 +0,0 @@ -# Regelrett frontend - -Velkommen til Regelrett-prosjektet bygget med React, Vite og TypeScript. Denne README-en vil veilede deg gjennom -oppsett, utvikling og vedlikehold av prosjektet. -Følg stegene nedenfor for å komme i gang og bruk de tilgjengelige skriptene for å administrere prosjektet effektivt. - -## Innholdsfortegnelse - -- [Forutsetninger](#forutsetninger) -- [Kom i Gang](#kom-i-gang) -- [Linting og Formatering](#linting-og-formatering) -- [Bygge for Produksjon](#bygge-for-produksjon) -- [Forhåndsvisning av Bygget](#forhåndsvisning-av-bygget) -- [Pre-commit Hooks](#pre-commit-hooks) -- [Nettverksforespørsler med TanStack Query](#nettverksforesporsler) - -## Forutsetninger - -Før du begynner, sørg for at du har følgende installert: - -- **[Node.js](https://nodejs.org)** (versjon 14.x eller nyere) -- **[npm](https://www.npmjs.com/get-npm)** eller **yarn** - -## Kom i Gang - -Følg disse stegene for å sette opp prosjektet lokalt: - -1. **Klon repositoriet**: - ```bash - git clone - cd /frontend/beCompliant - ``` - -2. **Installer avhengigheter:**: - ```bash - npm install - ``` - eller - ```bash - yarn install - ``` - -3. **Forbered Husky (hvis aktuelt):** - ```bash - npm run prepare - ``` - -4. **Start utviklingsserveren:** - ```bash - npm run dev - ``` - -Dette vil starte Vite utviklingsserveren, og du kan se appen på http://localhost:3000. - -## Linting og Formatering - -### Linting - -For å sikre kodekvalitet, kjør lint-verktøyet: - -```bash -npm run lint -``` - -For å automatisk fikse lintingproblemer: - -```bash -npm run lint-fix -``` - -` - -### Formatering - -For å formatere kodebasen med Prettier: - -```bash -npm run format -``` - -Dette vil formatere alle filer i src-mappen - -## Bygge for Produksjon - -For å lage en produksjonsklar versjon av prosjektet: - -```bash -npm run build -``` - -` -Dette vil kompilere TypeScript-filene og pakke applikasjonen ved hjelp av Vite. Output vil bli plassert i dist-mappen, -klar for utrulling. - -## Forhåndsvisning av Bygget - -Før du ruller ut, kan du forhåndsvise produksjonsbygget lokalt: - -```bash -npm run preview -``` - -` -Denne kommandoen vil servere produksjonsbygget på en lokal server, slik at du kan verifisere at alt fungerer som -forventet. - -## Pre-commit Hooks - -Husky er konfigurert til å kjøre visse skript før commits blir fullført. Dette inkluderer linting og TypeScript-sjekker -for å sikre kodekvalitet og konsistens. - -For å manuelt utløse disse sjekkene, kan du kjøre: - -```bash -npm run pre-commit -``` - -Dette vil kjøre lint-staged for å sjekke de stage’ede filene og sikre at TypeScript-filene er feilfrie før de blir -committet. - -

Nettverksforespørsler med TanStack Query

- -Dette prosjektet bruker TanStack Query (tidligere kjent som React Query) for å håndtere nettverksforespørsler og -servertilstand. TanStack Query forenkler datainnhenting, caching, synkronisering og oppdatering av servertilstand i -React-applikasjoner. Ved å bruke dette kraftige biblioteket sikrer prosjektet effektiv og pålitelig datahåndtering, -minimerer unødvendige nettverksforespørsler, og gir en optimal brukeropplevelse med automatiske bakgrunnsoppdateringer -og feilhåndtering. - -Se documentationen for Tanstack Query her https://tanstack.com/query/latest - -# Bygg og deployment - -For mer dokumentation om [Build and deployment](./docs/build-and-deployment.md)