126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# OC Catalog
|
||
|
||
## OpenCloud Catalog API
|
||
|
||
Uses the Beego framework
|
||
|
||
To install the Beego bee command :
|
||
|
||
go install github.com/beego/bee/v2@master
|
||
|
||
## Running the app locally
|
||
In order to run the application we need to correct some errors that beego generates.
|
||
|
||
**Router generation**
|
||
|
||
Beego generates the routers from the comment of the controllers methods. However, there seems to be some errors when we let beego generate th routers from `bee run`.
|
||
|
||
We need to use `bee generate routers` to have a working router file.
|
||
|
||
**Swagger generation**
|
||
|
||
Using `bee run -downdoc=true -gendoc=true` beego download a swagger template and generate the JSON file (swagger.json) in `swagger/`. However the swagger template in `swagger/index.html` does not change the exemple's url for our current JSON file. When running locally we have to edit the call to construct the object holding the swagger information, with the parameter url set with the relative path to our JSON swagger file :
|
||
|
||
```
|
||
const ui = SwaggerUIBundle({
|
||
url: "swagger.json",
|
||
...
|
||
...
|
||
});
|
||
```
|
||
|
||
This issue is fixed in the Dockerfile build with two `sed` to change the value of the swagger file URL.
|
||
|
||
## Deployment with Docker compose
|
||
## Running the app locally
|
||
In order to run the application we need to correct some errors that beego generates.
|
||
|
||
**Router generation**
|
||
|
||
Beego generates the routers from the comment of the controllers methods. However, there seems to be some errors when we let beego generate th routers from `bee run`.
|
||
|
||
We need to use `bee generate routers` to have a working router file.
|
||
|
||
**Swagger generation**
|
||
|
||
Using `bee run -downdoc=true -gendoc=true` beego download a swagger template and generate the JSON file (swagger.json) in `swagger/`. However the swagger template in `swagger/index.html` does not change the exemple's url for our current JSON file. When running locally we have to edit the call to construct the object holding the swagger information, with the parameter url set with the relative path to our JSON swagger file :
|
||
|
||
```
|
||
const ui = SwaggerUIBundle({
|
||
url: "swagger.json",
|
||
...
|
||
...
|
||
});
|
||
```
|
||
|
||
This issue is fixed in the Dockerfile build with two `sed` to change the value of the swagger file URL.
|
||
|
||
## Deployment with Docker compose
|
||
|
||
Deploy with docker:
|
||
`docker-compose -f docker-compose.yml -f docker-compose.backend.yml up --build`
|
||
|
||
and populate DB (or other scripts) with:
|
||
`docker exec -it oc-catalog_oc-catalog_1 ./scripts/populate_models.sh ./scripts/demo.json`
|
||
|
||
or out of docker `./scripts/populate_models.sh ./scripts/demo.json`
|
||
|
||
### Dev
|
||
|
||
- Start DB with `docker-compose up -d`
|
||
- Run the API with `bee run -downdoc=true -gendoc=true`
|
||
|
||
|
||
### Multinode
|
||
|
||
Deploy :
|
||
### Multinode
|
||
|
||
Deploy :
|
||
|
||
`docker-compose -f docker-compose.yml -f docker-compose.backend.yml -f docker-compose.multi.yml up --build`
|
||
|
||
## Populating the MongoDB database
|
||
|
||
On the machine running the mongoDB container, from the root of the project run this line :
|
||
|
||
`./scripts/populate_models.sh ./scripts/demo.json`
|
||
|
||
This script should be updated to be ran from anywhere.
|
||
|
||
# More documentation
|
||
|
||
[Visit the docs/ directory](/docs/)
|
||
|
||
## UML
|
||
|
||
We are currently using [goplantuml](https://github.com/jfeliu007/goplantuml/) to generate the oject diagrams directly from the go files. This tools creates `.plums` files directly from the directory where the go files are located. These UML files can then be visualized using plantuml and the VS Code extensions plantuml.
|
||
|
||
**Setting up the plantuml environment** :
|
||
|
||
```
|
||
# Downloading the go tool goplantuml
|
||
go get github.com/jfeliu007/goplantuml/parser
|
||
go install github.com/jfeliu007/goplantuml/cmd/goplantuml@latest
|
||
|
||
# Install the plantuml environment
|
||
sudo apt install default-jre
|
||
sudo apt install plantuml
|
||
|
||
```
|
||
**Rich PlantUML extension Link**: https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml or search it in the marketplace panel of VS Code
|
||
|
||
**Generate and view an UML diagram**
|
||
|
||
```
|
||
goplantuml path/to/code/directory > path/to/dest/file.puml
|
||
```
|
||
|
||
- open the .puml file generated
|
||
- alt + d to have the extension preview the plantUML code
|
||
- right click inside the .puml and select 'Export Current Diagram' to create an image file
|
||
- the output will be generated in a `out/` directory in the current path
|
||
|
||
### Note
|
||
|
||
Only `.puml` files ought to be commited to the git repository, because their nature allows to track changes, while image file do not fit the purpose of versioning. |