README.md 3.49 KB
Newer Older
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
1
2
3
4
5
6
# BoCo - Backend

This is the API for the Borrow Company web application. The corresponding frontend is located [here](https://gitlab.stud.idi.ntnu.no/idatt2106_2022_02/boco-frontend).

This project was developed between the 19th of April and The 6th of May, 2022 for the course *IDATT2106 - System development 2 with flexible project* at NTNU. Development follow the agile SCRUM workflow, and was divided into two distinct sprints with corresponding planning and review.

7
## Run Locally
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
8

9
Clone the project [*with SSH*](https://docs.gitlab.com/ee/user/ssh.html)
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
10

11
12
13
```bash
  git clone git@gitlab.stud.idi.ntnu.no:idatt2106_2022_02/boco-backend.git
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
14

15
Go to the project directory
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
16

17
18
```bash
  cd boco-backend
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
19
20
```

21
#### Environment variables
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
22

23
24
25
26
To run our backend, a configuration file is needed.
- Create a ``.env`` file in the projects root directory.
- Copy paste the following fields into the file.
- If you want to, you can edit the default values with your own configuration. Especially the password should be randomly generated and hard to guess. Remember to make sure the configuration is consistent with the frontend.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
27

28
29
30
31
32
33
```file
POSTGRES_DB=bocodb
POSTGRES_IP=localhost
POSTGRES_PORT=5432
POSTGRES_USER=boco
POSTGRES_PASS=superSecureMegaAwesomePassword
34
SERVER_PORT=3000
35
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
36

37
#### Running with Docker compose
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
38

Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
39
By far the easiest way to run our backend is through Docker Compose. This is because it automatically configures and runs both the PostgreSQL database and the backend for you.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
40

41
To do this you need to install [Docker](https://docs.docker.com/get-docker/), and if you're on Linux you also need to install [Docker Compose](https://docs.docker.com/compose/install/) independently.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
42

43
When you have installed Docker and Docker Compose, simply run
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
44

45
46
47
```bash
docker-compose up
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
48

49
Docker will now start two containers; one running a PostgreSQL database and one running our backend application.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
50
51


52
When you want to shut down the containers run
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
53

54
55
56
```bash
docker-compose down
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
57

58
If you edit the code, you will need to rebuild the application with
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
59

60
*Note: if you want to change any docker/environment variables you also need to shut down the containers before rebuilding.*
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
61

62
63
64
```bash
docker-compose up --build
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
65

66
If you want to delete the database contents or change anything about the database configuration (for example the environment variables); shut down the containers, then delete the Docker volume containing the database data.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
67

68
69
70
71
```bash
docker-compose down
docker volume rm boco-backend_boco-data
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
72
73


74
#### Running natively
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
75

76
First and foremost, to run our backend you need a running [PostgreSQL](https://www.postgresql.org/download/) database.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
77

78
You also need to install the [JDK](https://www.oracle.com/java/technologies/downloads/) (Java Development Kit). Under development of the API, version 17 LTS (Long Term Support) was used. 
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
79

80
Afterwards, you need to install [Apache Maven](https://maven.apache.org/index.html), our dependency manager of choice.
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
81

Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
82
83
Then you need to uncomment the PostgreSQL config in the ``application.properties`` file located at ``src/main/resources/``. 

84
Finally, you can run the API with
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
85

86
87
88
```bash
  mvn spring-boot:run
```
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
89

Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
90
91
92
93
94
95
96
97

## Running Tests

To run tests, run the following command

```bash
  mvn clean test
```
98
After running the tests a test coverage report will be produced. This report is located in the folder `target/site`
Erik Borgeteien Hansen's avatar
Erik Borgeteien Hansen committed
99
100

When building through Docker Compose, Docker automatically runs the tests and stops the launching process at failures.
101
102

## API Documentation
103
[API Docs via swagger](http://localhost:3000/api/swagger-ui/index.html#/)