Skip to content

Commit b8c7eb6

Browse files
author
Derek Wasinger
committed
updated readme
1 parent 6b7a72e commit b8c7eb6

File tree

1 file changed

+98
-38
lines changed

1 file changed

+98
-38
lines changed

‎README.md‎

Lines changed: 98 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,126 @@
11
![Container Build](https://github.com/rht-labs/open-management-portal-git-api/workflows/Container%20Build/badge.svg)
22

3-
# open-management-portal-git-api project
3+
# Open Management Portal - Git API
44

5-
This project uses Quarkus, the Supersonic Subatomic Java Framework.
6-
If you want to learn more about Quarkus, please visit its website: https://quarkus.io/ .
5+
The Git API for the Open Management Portal.
76

8-
## Running the application
7+
This API uses GitLab as a repository to store OMP resources.
98

10-
Prior to running the app, you need to create a **Personal Access Token** linked to your GitLab account.
9+
## JSON REST APIs
10+
11+
The JSON REST APIs consist of the following resources:
12+
13+
* Config
14+
* Engagements
15+
* Version
16+
17+
### Config Resource
18+
19+
The config resource exposes an API that allows clients to retrieve a configured `Config` file from GitLab.
1120

12-
You could edit your bash profile and make your Quarkus quacky by adding this neat emoji alias, then all you need to fire up your app is run 🦆
1321
```
14-
echo "alias 🦆='./mvnw quarkus:dev -Dquarkus.http.port=8080'" >> ~/.zshrc
15-
source ~/.zshrc
22+
GET /api/v1/config
23+
```
1624

17-
🦆
25+
### Engagement Resource
26+
27+
The engagement resource exposes an API that allows clients to create or update and engagement resource in GitLab.
28+
29+
```
30+
POST /api/v1/engagements
1831
```
1932

20-
### Running with a profile
33+
This endpoint will create the expected group/project structure in GitLab. Then, will update the `engagement.json` file if it already exists or create it if it does not.
34+
35+
### Version Resource
36+
37+
The version resource exposes an API that allows a client to determine which version of the application is deployed.
2138

22-
You can run your application using Quarkus profiles using:
2339
```
24-
export CONFIG_REPOSITORY_ID =<Git Repo id where the config files are>
25-
export GITLAB_API_URL=<The base url of your git api. ie https://gitlab.com>
26-
export GITLAB_PERSONAL_ACCESS_TOKEN=<GitLab Personal Access Token>
27-
export OMP_LOGGING=DEBUG
28-
export RESIDENCIES_PARENT_REPOSITORIES_ID=<Parent project id where repos will be saved>
29-
export TEMPLATE_REPOSITORY_ID=<Repo where template live>
30-
export QUARKUS_PROFILE=<Quarkus profile>
31-
./mvnw clean package
32-
java -jar target/open-management-portal-git-api-*-runner.jar
40+
GET /api/v1/version
3341
```
3442

35-
## Packaging and running the application
43+
## Configuration
44+
45+
The preferred place to store non-sensitive data is in the application.properties.
3646

37-
The application is packageable using `./mvnw package`.
38-
It produces the executable `open-management-portal-git-api-1.0.0-SNAPSHOT-runner.jar` file in `/target` directory.
39-
Be aware that it’s not an _über-jar_ as the dependencies are copied into the `target/lib` directory.
47+
Sensitive fields like the gitlab token and cluster credentials should be stored in a OpenShift secret at a minimum. Other environment specific information should be stored in environmental variables such as repository id for engagements and repository id for the config.
4048

41-
The application is now runnable using `java -jar target/open-management-portal-git-api-1.0.0-SNAPSHOT-runner.jar`.
49+
Deployment template will read from the above secret and inject following env variables. These are controlled from application.properties, so if a different env name is needed, change in the application properties file and the deployment template.
4250

43-
## Creating a native executable
51+
### Logging
4452

45-
You can create a native executable using: `./mvnw package -Pnative`.
53+
| Name | Example Value | Required |
54+
|------|---------------|----------|
55+
| OMP_LOGGING | DEBUG | False |
4656

47-
Or you can use Podman to build the native executable using: `./mvnw package -Pnative -Dquarkus.native.container-runtime=podman`.
57+
# GitLab
4858

49-
You can then execute your binary: `./target/open-management-portal-git-api-1.0.0-SNAPSHOT-runner`
59+
| Name | Example Value | Required |
60+
|------|---------------|----------|
61+
| GITLAB_API_URL | https://acmegit.com | True |
62+
| DEPLOY_KEY | 0 | True |
5063

51-
If you want to learn more about building native executables, please consult https://quarkus.io/guides/building-native-image-guide .
64+
# Config Resource
5265

66+
| Name | Example Value | Required |
67+
|------|---------------|----------|
68+
| CONFIG_REPOSITORY_ID | 1 | True |
69+
| CONFIG_FILE | my-config.yml | True |
5370

54-
## Configuration
71+
# Engagements Resource
5572

56-
The preferred place to store non-sensitive data is in the application.properties.
73+
| Name | Example Value | Required |
74+
|------|---------------|----------|
75+
| ENGAGEMENTS_REPOSITORY_ID | 2 | True |
5776

58-
Sensitive fields like the gitlab token and cluster credentials should be stored in a OpenShift secret at a minimum. Other environment specific information should be stored in environmental variables such as repository id for residencies and repository id for the config.
77+
# Version Resource
5978

60-
Deployment template will read from the above secret and inject following env variables. These are controlled from application.properties, so if a different env name is needed, change in the application properties file and the deployment template.
79+
| Name | Example Value | Required |
80+
|------|---------------|----------|
81+
| GIT_API_GIT_COMMIT | a2adfk | False |
82+
| GIT_API_GIT_TAG | v1.2 | False |
83+
84+
## Development
6185

62-
* `TEMPLATE_REPOSITORY_ID`
63-
* `RESIDENCIES_PARENT_REPOSITORIES_ID`
64-
* `GITLAB_API_URL`
65-
* `GITLAB_PERSONAL_ACCESS_TOKEN` (should be secret and a service account)
86+
See [the deployment README](deployment/README.md) for details on how to spin up a deployment for developing on OpenShift.
6687

88+
89+
## Running the application
90+
91+
Prior to running the app, you need to create a **Personal Access Token** linked to your GitLab account.
92+
93+
You could edit your bash profile and make your Quarkus quacky by adding this neat emoji alias, then all you need to fire up your app is run 🦆
94+
```
95+
echo "alias 🦆='./mvnw quarkus:dev -Dquarkus.http.port=8080'" >> ~/.zshrc
96+
source ~/.zshrc
97+
98+
🦆
99+
```
100+
101+
### Running the Application
102+
103+
You can run your application using Quarkus using:
104+
105+
```
106+
107+
# logging
108+
export OMP_LOGGING=DEBUG
109+
110+
# gitlab
111+
export GITLAB_API_URL=<The base url of your git api. ie https://gitlab.com>
112+
export GITLAB_PERSONAL_ACCESS_TOKEN=<GitLab Personal Access Token>
113+
export DEPLOY_KEY=<Deployment Key for Engagements>
114+
115+
# config
116+
export CONFIG_REPOSITORY_ID=<Git Repo id where the config files are>
117+
118+
# engagements
119+
export ENGAGEMENTS_REPOSITORY_ID=<Parent project id where repos will be saved>
120+
121+
# package the application
122+
./mvnw clean package
123+
124+
# run the application
125+
java -jar target/open-management-portal-git-api-*-runner.jar
126+
```

0 commit comments

Comments
 (0)