From 6fac5e20974ceb5e29927dc3947a548b98ae5b04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Max=20K=C3=A4stner?= Date: Fri, 13 May 2022 16:15:40 +0200 Subject: [PATCH 1/4] Initial commit for login-backend documentation --- dev-manuals/login-backend/README.md | 88 ++++++++++++++++++++++++++++ user-manuals/login-backend/README.md | 54 +++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 dev-manuals/login-backend/README.md create mode 100644 user-manuals/login-backend/README.md diff --git a/dev-manuals/login-backend/README.md b/dev-manuals/login-backend/README.md new file mode 100644 index 00000000..e8509496 --- /dev/null +++ b/dev-manuals/login-backend/README.md @@ -0,0 +1,88 @@ +# Login Backend +This Markdown file contains all necessary informations for developers about the Login Backend repository. + +## Requirements +- Go https://go.dev 1.16 or higher +- GoLand: https://www.jetbrains.com/go/ for running start scripts in IDE +- Docker / Docker desktop: https://www.docker.com/products/docker-desktop to build and run as docker container +- (Postgres database) + +## Starting with this repository +First, make sure Goland knows your Docker path: Check in +`Files -> Settings -> Build, Execution, Deployment -> Docker` +If in the left coloumn is no Docker registered, add Docker by clicking the top left add Button. + +## Project structure + +| File / Directory | Description | +|--------------------------------------|-------------------------------------------------------------------------------------------| +| `main.go` | Entry point of the program | +| `swagger/` | Contains the API specification (Swagger) | +| `prisma/` | Database schema (Prisma) | +| `src/handlers/` | Our HTTP handler implementations (Go) | +| `src/handlers/handlers.go` | Adds all our handler functions to the server | +| `src/gen/` | Generated files from Prisma and Swagger. Do not edit or commit generated files! | +| `src/gen/restapi/configure_login.go` | Configuration for the HTTP server. The only file in `src/gen/` that can be safely edited. | + +This repository contains run configurations which are loaded automatically when you open the project in GoLand. To run the project, select the go build configuration in the top right toolbar. + +## Run application +You can run the application in three ways. +- Directly from GoLand +- Command line with go commands +- Build docker image and run a container + +### In IDE +The `go build` configuration (top right of GoLand) performs the following tasks for you: + +- starts a postgres database with docker +- generates the Swagger code for the server +- generates the Prisma database client +- compiles & runs the project + +### From command line +You need to run your own postgres database. +```sh +export PORT=4000 +export POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres # Update credentials +export JWT_KEY=secretKey + +go generate +go run github.com/prisma/prisma-client-go migrate deploy # When there is new database scheme, it needs to mirgrate +go run . + +``` + +### From Dockerfile +You need to run your own postgres database. + +#### Build docker image +```sh +docker build -t login-backend . +``` +#### Start container +```sh +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres" -e "JWT_KEY=secretKey" +``` + + +## Migrating the database +When changes to the database are made, you can create a migration by running +```sh +POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres go run github.com/prisma/prisma-client-go migrate dev --name $MIGRATION_NAME +``` +inside the project root dir.\ +To apply all pending migrations, simply run +```sh +POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres go run github.com/prisma/prisma-client-go migrate deploy +``` +inside the project root dir. + +## JWT (Json Web Tokens) +To encode a JWT, a secret key is needed. +This secret key needs to be stored under the environment variable `JWT_KEY`. + +## Go-Swagger +This Rest-API uses Go-Swagger. So the `swagger/swagger.yml` is the base of the rest api. You find documentation about the swagger.yml here: https://swagger.io/docs/specification/basic-structure/. + +After changes were made in `swagger.yml` file you should run `go genrate` that the files will be generated. With the generated objects you can work. \ No newline at end of file diff --git a/user-manuals/login-backend/README.md b/user-manuals/login-backend/README.md new file mode 100644 index 00000000..1a93a7cd --- /dev/null +++ b/user-manuals/login-backend/README.md @@ -0,0 +1,54 @@ +# Login Backend +This Markdown file contains all necessary informations for end users about the Login Backend repository. + +## Requirements +- Go https://go.dev 1.16 or higher +- Docker https://www.docker.com/ to run docker containers +- Postgres database + +## Run application +You can run the application in two ways. +- Command line with go commands +- Build docker image and run a container + +### From command line +You need to run your own postgres database. +```sh +export PORT=4000 +export POSTGRES_URL=postgresql://:@:/ # Update key words in '<>' with your credentials +export JWT_KEY=secretKey + +go generate +go run github.com/prisma/prisma-client-go migrate deploy # When there is new database scheme, it needs to mirgrate +go run . + +``` + +### From Dockerfile + +#### Build docker image +```sh +docker build -t login-backend . +``` +Or get it from our Github Package Registry if you have access to it +```sh +docker pull ghcr.io/gamify-it/login-backend:latest +``` + +#### Start container +```sh +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=secretKey" +``` +Update key words in '<>' with your credentials + + +## Migrating the database +When changes to the database are made, apply all pending migrations, simply run +```sh +POSTGRES_URL=postgresql://:@:/ go run github.com/prisma/prisma-client-go migrate deploy +``` + +## JWT (Json Web Tokens) +To encode a JWT, a secret key is needed. +This secret key needs to be stored under the environment variable `JWT_KEY`. +KEEP IT PRIVATE! From b562495fb9c36b4b1b57796f01bca53b69c82f87 Mon Sep 17 00:00:00 2001 From: Max <39833217+maexled@users.noreply.github.com> Date: Fri, 13 May 2022 19:23:11 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: delvh --- dev-manuals/login-backend/README.md | 15 ++++++++------- user-manuals/login-backend/README.md | 19 +++++++++---------- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/dev-manuals/login-backend/README.md b/dev-manuals/login-backend/README.md index e8509496..a05616c1 100644 --- a/dev-manuals/login-backend/README.md +++ b/dev-manuals/login-backend/README.md @@ -2,15 +2,16 @@ This Markdown file contains all necessary informations for developers about the Login Backend repository. ## Requirements -- Go https://go.dev 1.16 or higher -- GoLand: https://www.jetbrains.com/go/ for running start scripts in IDE -- Docker / Docker desktop: https://www.docker.com/products/docker-desktop to build and run as docker container -- (Postgres database) +- [Go](https://go.dev) 1.16 or higher +- [GoLand](https://www.jetbrains.com/go/) as IDE +- [Docker](https://www.docker.com/) to run docker containers +- ([Docker Desktop](https://www.docker.com/products/docker-desktop) to build and run docker containers graphically) +- ([Postgres](https://www.postgresql.org/) database) ## Starting with this repository First, make sure Goland knows your Docker path: Check in `Files -> Settings -> Build, Execution, Deployment -> Docker` -If in the left coloumn is no Docker registered, add Docker by clicking the top left add Button. +If in the left column no Docker is registered, add Docker by clicking the top left add Button. The system Docker (suggested by default) should suffice. ## Project structure @@ -83,6 +84,6 @@ To encode a JWT, a secret key is needed. This secret key needs to be stored under the environment variable `JWT_KEY`. ## Go-Swagger -This Rest-API uses Go-Swagger. So the `swagger/swagger.yml` is the base of the rest api. You find documentation about the swagger.yml here: https://swagger.io/docs/specification/basic-structure/. +This Rest-API uses Go-Swagger. So the `swagger/swagger.yml` is the base of the rest api. You find documentation about the _swagger.yml_ [here](https://swagger.io/docs/specification/basic-structure/). -After changes were made in `swagger.yml` file you should run `go genrate` that the files will be generated. With the generated objects you can work. \ No newline at end of file +After changes were made in the `swagger.yml` file you should run `go generate` so that the files will be generated. You can work with these generated objects. \ No newline at end of file diff --git a/user-manuals/login-backend/README.md b/user-manuals/login-backend/README.md index 1a93a7cd..b0482337 100644 --- a/user-manuals/login-backend/README.md +++ b/user-manuals/login-backend/README.md @@ -2,9 +2,9 @@ This Markdown file contains all necessary informations for end users about the Login Backend repository. ## Requirements -- Go https://go.dev 1.16 or higher -- Docker https://www.docker.com/ to run docker containers -- Postgres database +- [Go](https://go.dev) 1.16 or higher +- [Docker](https://www.docker.com/) to run docker containers +- [Postgres](https://www.postgresql.org/) database ## Run application You can run the application in two ways. @@ -16,12 +16,11 @@ You need to run your own postgres database. ```sh export PORT=4000 export POSTGRES_URL=postgresql://:@:/ # Update key words in '<>' with your credentials -export JWT_KEY=secretKey +export JWT_KEY= go generate -go run github.com/prisma/prisma-client-go migrate deploy # When there is new database scheme, it needs to mirgrate +go run github.com/prisma/prisma-client-go migrate deploy # Migrate database scheme if it has changed go run . - ``` ### From Dockerfile @@ -37,13 +36,13 @@ docker pull ghcr.io/gamify-it/login-backend:latest #### Start container ```sh -docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=secretKey" +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" ``` -Update key words in '<>' with your credentials +Replace `<.*>` with the corresponding credentials. -## Migrating the database -When changes to the database are made, apply all pending migrations, simply run +## Updating +When you update the login backend, changes to the database could have been made, so make sure to migrate the database structure simply by running ```sh POSTGRES_URL=postgresql://:@:/ go run github.com/prisma/prisma-client-go migrate deploy ``` From d0e09f4828b5b9a433cfb68c5767307ddb514971 Mon Sep 17 00:00:00 2001 From: Max <39833217+maexled@users.noreply.github.com> Date: Fri, 13 May 2022 22:38:51 +0200 Subject: [PATCH 3/4] Corrected wrong variable in <> --- user-manuals/login-backend/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user-manuals/login-backend/README.md b/user-manuals/login-backend/README.md index b0482337..121b9a21 100644 --- a/user-manuals/login-backend/README.md +++ b/user-manuals/login-backend/README.md @@ -15,7 +15,7 @@ You can run the application in two ways. You need to run your own postgres database. ```sh export PORT=4000 -export POSTGRES_URL=postgresql://:@:/ # Update key words in '<>' with your credentials +export POSTGRES_URL=postgresql://:@:/ # Update key words in '<>' with your credentials export JWT_KEY= go generate @@ -36,7 +36,7 @@ docker pull ghcr.io/gamify-it/login-backend:latest #### Start container ```sh -docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" ``` Replace `<.*>` with the corresponding credentials. @@ -44,7 +44,7 @@ Replace `<.*>` with the corresponding credentials. ## Updating When you update the login backend, changes to the database could have been made, so make sure to migrate the database structure simply by running ```sh -POSTGRES_URL=postgresql://:@:/ go run github.com/prisma/prisma-client-go migrate deploy +POSTGRES_URL=postgresql://:@:/ go run github.com/prisma/prisma-client-go migrate deploy ``` ## JWT (Json Web Tokens) From 8e05fc1531224757e3cbd3fa20b90182f6712802 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Max=20K=C3=A4stner?= Date: Sat, 14 May 2022 15:22:57 +0200 Subject: [PATCH 4/4] added image name to docker run command --- dev-manuals/login-backend/README.md | 2 +- user-manuals/login-backend/README.md | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/dev-manuals/login-backend/README.md b/dev-manuals/login-backend/README.md index a05616c1..0e4b9325 100644 --- a/dev-manuals/login-backend/README.md +++ b/dev-manuals/login-backend/README.md @@ -63,7 +63,7 @@ docker build -t login-backend . ``` #### Start container ```sh -docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres" -e "JWT_KEY=secretKey" +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://postgres:password@localhost:5432/postgres" -e "JWT_KEY=secretKey" login-backend ``` diff --git a/user-manuals/login-backend/README.md b/user-manuals/login-backend/README.md index 121b9a21..73feee81 100644 --- a/user-manuals/login-backend/README.md +++ b/user-manuals/login-backend/README.md @@ -35,8 +35,13 @@ docker pull ghcr.io/gamify-it/login-backend:latest ``` #### Start container +If you build your image yourself, run following ```sh -docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" login-backend +``` +Or in case you pulled from Github Package Registry, run +```sh +docker run --name login-backend -p 4000:4000 -e "POSTGRES_URL=postgresql://:@:/" -e "JWT_KEY=" ghcr.io/gamify-it/login-backend:latest ``` Replace `<.*>` with the corresponding credentials.