|
2 | 2 |
|
3 | 3 | Template app for spring boot applications |
4 | 4 |
|
5 | | -#Functionalities |
6 | | - |
7 | | -A short description of api functionalities |
8 | | - |
9 | | -#Diagrams |
10 | | - |
11 | | -Link to diagramas in the context of this API |
12 | | -<https://github.com/devxp-tech-group/diagrams/tree/main/> |
13 | | - |
14 | | -``` |
15 | | -You could add images, just copying these tag with correct links |
16 | | - |
17 | | -``` |
18 | | - |
19 | | -#Hosts |
20 | | - |
21 | | -- Local:<http://localhost:8080/api> |
22 | | -- QA Private:<https://ms-template.priv.qa.devxp-tech.local/api> |
23 | | -- QA Public:<https://ms-template.pub.qa.devxp-tech.io/api> |
24 | | -- Live Private:<https://ms-template.priv.live.devxp-tech.local/api> |
25 | | -- Live Public:<https://ms-template.pub.live.devxp-tech.io/api> |
26 | | - |
27 | | -#Documentation |
28 | | - |
29 | | -Open API docs |
30 | | - |
31 | | -- Local:<http://localhost:8080/api/swagger-ui.html> |
32 | | -- QA:<https://ms-template.priv.qa.devxp-tech.local/swagger-ui.html> |
33 | | -- Live:<https://ms-template.priv.live.devxp-tech.local/swagger-ui.html> |
34 | | - |
35 | | -#Setup |
36 | | - |
37 | | -- Download Intellij:<https://www.jetbrains.com/idea/download/> |
38 | | -- Enable plugins of Spring/SpringBoot if available |
39 | | -- Setup JDK (openjdk11-openj9) |
40 | | -- Enable "EditorConfig" in -> Preferences | Editor | Code Style |
41 | | -- If it's needed, setup your nexus credentials with script 'setup-nexus-credentials.sh' |
42 | | -- Enjoy! |
43 | | - |
44 | | -#Common commands |
45 | | - |
46 | | -``` |
47 | | -Build: ./gradlew build |
48 | | -Docker Build: docker build -t app-template . |
49 | | -Run docker container: docker run -it --rm app-template |
50 | | -Run docker compose: docker-compose up |
51 | | -Run docker compose only database: docker-compose up postgres |
52 | | -Check code style: eclint check "src/**" (Need to install 'npm install -g eclint') |
53 | | -``` |
54 | | - |
55 | | -#USING TEMPLATE |
56 | | - |
57 | | -Steps to use this template: |
58 | | - |
59 | | -- Create a new repository with a template |
60 | | -- Rename 'apptemplate" package |
61 | | -- Read all config steps and apply modifications*** Don't skip any step! |
62 | | -- Delete unused classes, if you dont need a example |
63 | | -- Rename app name in application.yml -> app.name |
64 | | -- Uncomment code in .circleci/config.yml |
65 | | -- Rename docker image (ms-template) in .circleci/config.yml |
66 | | -- Rename ingress, IAMRole and overlay name in deploy/charts (QA/Live) |
67 | | -- If all build tests are OK, remove this section of readme and start coding :) |
68 | | - |
69 | | -##Configuration |
70 | | - |
71 | | -Initial configs to use this template, take a time to read everything! |
72 | | - |
73 | | -###Log |
74 | | - |
75 | | -``` |
76 | | -All default log configs are stored in src/main/resources/logback.xml |
77 | | -Log json template could be edited in bootstrap repository |
78 | | -``` |
79 | | - |
80 | | -###HealthCheck |
81 | | - |
82 | | -``` |
83 | | -Enabling: automatically enabled. To add a new health-check, add a @Service that implements HealthService.java |
84 | | -See GoogleHealthCheckService.java for example |
85 | | -
|
86 | | -Disabling: Health Check cannot be disabled |
87 | | -``` |
88 | | - |
89 | | -###Security |
90 | | - |
91 | | -``` |
92 | | -Enabling: Just keep the class SecurityConfig.java, and remember to add the following code on your controller methods |
93 | | -@Unauthorized |
94 | | -@SecurityRequirement(name = "bearerAuth") |
95 | | -
|
96 | | -Disabling: Delete class SecurityConfig.java, and remove these fields in application.yml |
97 | | - jwt-secret: ${JWT_SECRET:secret} |
98 | | - jwt-expiration-time-minutes: ${JWT_EXPIRATION_TIME_MINUTES:30} |
99 | | - api-user-name: ${API_USER:user} |
100 | | - api-pass: ${API_PASSWORD:password} |
101 | | -
|
102 | | -Remember to remove @Unauthorized and @SecurityRequirement annotations in controller methods too |
103 | | -Remove lib implementation 'org.springframework.boot:spring-boot-starter-security' |
104 | | -``` |
105 | | - |
106 | | -###Messaging |
107 | | - |
108 | | -``` |
109 | | -Enabling: Edit these configs to application.yaml and create your @JmsListener |
110 | | -
|
111 | | -aws: |
112 | | - sqs: |
113 | | - max-tries: ${AWS_SQS_MAX_TRIES:5} |
114 | | - local-endpoint: ${AWS_SQS_ENDPOINT:http://localhost:9324} |
115 | | - region: ${AWS_REGION:us-east-1} |
116 | | -
|
117 | | -Disabling: Remove above code in application.yml |
118 | | -
|
119 | | -Remove this code in .circleci/config.yml |
120 | | -
|
121 | | - - run: |
122 | | - name: Run SQS |
123 | | - command: | |
124 | | - wget https://s3-eu-west-1.amazonaws.com/softwaremill-public/elasticmq-server-0.14.6.jar |
125 | | - java -Dconfig.file=elasticmq.conf -jar elasticmq-server-0.14.6.jar |
126 | | - background: true |
127 | | -
|
128 | | -Remove sqs container in docker-compose.yaml |
129 | | -
|
130 | | - sqs: |
131 | | - image: s12v/elasticmq |
132 | | - ports: |
133 | | - - "9324:9324" |
134 | | - volumes: |
135 | | - - ./elasticmq.conf:/etc/elasticmq/elasticmq.conf |
136 | | -
|
137 | | -Delete elasticmq.conf in root folder |
138 | | -Remove libs: |
139 | | - implementation 'org.springframework:spring-jms' |
140 | | - implementation 'com.amazonaws:aws-java-sdk:1.11.898' |
141 | | - implementation 'com.amazonaws:amazon-sqs-java-messaging-lib:1.0.8' |
142 | | -``` |
143 | | - |
144 | | -###Database |
145 | | - |
146 | | -``` |
147 | | -Enabling: Just edit these fields in application.yml |
148 | | -
|
149 | | -datasource: |
150 | | - name: ${DB_NAME:db_template} |
151 | | - host: ${DB_HOST:localhost:5432} |
152 | | - username: ${DB_USER:root} |
153 | | - password: ${DB_PASSWORD:root} |
154 | | -
|
155 | | -
|
156 | | -Disabling: Remove above code in application.yml, and add these exclusions to Application.java |
157 | | -
|
158 | | -@SpringBootApplication(exclude = { |
159 | | - DataSourceAutoConfiguration.class, |
160 | | - DataSourceTransactionManagerAutoConfiguration.class, |
161 | | - HibernateJpaAutoConfiguration.class, |
162 | | - LiquibaseAutoConfiguration.class |
163 | | -}) |
164 | | -
|
165 | | -Delete liquibase folder and hibernate.properties in src/main/resources/ |
166 | | -Delete database container in docker-composer.yaml |
167 | | -Delete the following code in .circleci/config.yml |
168 | | -
|
169 | | - - image: circleci/postgres:12.0-alpine-ram |
170 | | - environment: |
171 | | - POSTGRES_USER: root |
172 | | - POSTGRES_PASSWORD: root |
173 | | - POSTGRES_DB: db_template |
174 | | -
|
175 | | -Remove libs: |
176 | | - implementation 'org.springframework.boot:spring-boot-starter-data-jpa' |
177 | | -``` |
178 | | - |
179 | | -###Cache |
180 | | - |
181 | | -``` |
182 | | -Enabling: Add the annotation @EnableCaching to Application.java |
183 | | -Disabling: Remove libs: |
184 | | - implementation 'org.springframework.boot:spring-boot-starter-cache' |
185 | | -``` |
186 | | - |
187 | | -###Scheduling |
188 | | - |
189 | | -``` |
190 | | -Enabling: Add the annotation @EnableScheduling to Application.java |
191 | | -``` |
192 | | - |
193 | | -###Mocking (for tests or local environment) |
194 | | - |
195 | | -``` |
196 | | -Enabling: Add new mock files in mock/mappgins |
197 | | -You could read the docs here http://wiremock.org/docs/ |
198 | | -
|
199 | | -Disabling: Remove the following code in docker-compose.yaml |
200 | | -
|
201 | | - mock: |
202 | | - image: rodolpheche/wiremock:2.26.3-alpine |
203 | | - ports: |
204 | | - - "5000:8080" |
205 | | - - "8443:8443" |
206 | | - volumes: |
207 | | - - ${PWD}/mock:/home/wiremock |
208 | | -
|
209 | | -Delete mock folder |
210 | | -Remove the following code in .circleci/config.yml |
211 | | -
|
212 | | - - run: |
213 | | - name: Start wiremock |
214 | | - command: | |
215 | | - wget https://repo1.maven.org/maven2/com/github/tomakehurst/wiremock-standalone/2.26.3/wiremock-standalone-2.26.3.jar |
216 | | - cp wiremock-standalone-2.26.3.jar mock |
217 | | - cd mock |
218 | | - java -jar wiremock-standalone-2.26.3.jar --port 5000 |
219 | | - background: true |
220 | | -``` |
221 | | - |
222 | | -###Testing |
223 | | - |
224 | | -``` |
225 | | -Controller tests: Look at UserControllerTest.java for examples |
226 | | -Good to know: |
227 | | -- Unit test is only needed for complex operations |
228 | | -- Spring initialize a fake server before all tests |
229 | | -- All repositories and cache are cleared before/after tests |
230 | | -- Its possible to mock services and other classes (see ms-cobranded for more samples) |
231 | | -``` |
232 | | - |
233 | | -###Build & Review |
234 | | - |
235 | | -``` |
236 | | -Make sure of theeses steps: |
237 | | -- Granted access to all devxp-tech developers in repository -> settings -> manage access -> add grou developers |
238 | | -- Have branch protetion rules in repository -> settings -> branches (Require pull request views, status check before merging) |
239 | | -- Leave only "allow squash merging" in repository -> settings -> options -> merge button |
240 | | -- Setup project in circleci https://app.circleci.com/projects/project-dashboard/github/devxp-tech-group/ |
241 | | -- Added a SSH key in circleci project -> settings -> ssh keys |
242 | | -- Created a token in in circleci project -> settings -> API permissions |
243 | | -- Use token and correct URL in circleci badge in the beginning of this readme |
244 | | -- Have all environment variable configured in circleci project -> settings -> API environment variables |
245 | | -- Have all K8s resources created and applied in https://github.com/devxp-tech-group/ops (You could use another app as example) |
246 | | -- If is needed, create or ask a DBA to create RDS files in ops |
247 | | -- If is needed, create SQS, SNS, S3 terraform files in ops |
248 | | -- Create a elasticsearch index in ops |
249 | | -- Created ticket and ask SRE team to create a k8s namespace, and helm for QA/Live |
250 | | -- In case of live environemnt, create a ticket and ask sre team to encrypt live environments variablies |
251 | | -- Add index in graylog/kibana qa/live |
252 | | -- Add a new panel in Grafana for metrics and resources monitoring |
253 | | -- Create a ticket for personal and read-only access to databases ou AWS resources |
254 | | -
|
255 | | -After all theses steps: |
256 | | -- Test private and public ingress routes |
257 | | -- Test Grafana panels |
258 | | -- Test search for something in kibana |
259 | | -- Test pods access with kubelogin |
260 | | -- Test personal access for database and aws resources |
261 | | -``` |
262 | | - |
263 | | -#Deploy |
264 | | - |
265 | | -Currently, there are two delivery models: |
266 | | - |
267 | | -- Using CircleCI pipelines (legacy): |
268 | | -- Configure a`Build and Deploy` step defined in`.circleci/config.yml` |
269 | | -- Create following files on`deploy/chart/` folder: |
270 | | -- QA values:`qa-values.yaml` |
271 | | -- Live values:`live-values.yaml` |
272 | | -- Secrets file:`qa-secrets.yaml` |
273 | | -- Using ArgoCD (new): |
274 | | -- Create[ArgoCD](https://github.com/devxp-tech-group/argo/) configuration files for`service-name.yaml` (replace`service-name` with your project name): |
275 | | -- QA:`clusters/eks-qa-devxp-tech-latam/apps/service-name.yaml` |
276 | | -- Live:`clusters/eks-live-devxp-tech-latam/apps/service-name.yaml` |
277 | | -- Create a folder with the`service-name` under the[Charts](https://github.com/devxp-tech-group/charts) project with following files: |
278 | | -- Main chart file:`Chart.yaml` |
279 | | -- QA values:`qa-values.yaml` |
280 | | -- Live values:`values.yaml` |
281 | | -- Requirements file:`requirements.yaml` |
282 | | -- Add your`service-name` to filebeat config files on[OPS](https://github.com/devxp-tech-group/ops/) project: |
283 | | -- QA:`accounts/devxp-tech-dev/678591175058/envs/qa/us-east-1/10-clusters/qa.k8s.devxp-tech.local/manifests/10-logging/10-filebeat.yaml` |
284 | | -- Live:`accounts/gfg-live/556684128444/envs/live/us-east-1/10-clusters/live.k8s.devxp-tech.local/manifests/10-logging/10-filebeat.yaml` |