1
2# Development
3
4This document outlines steps for local development e2e testing of remotecli and all ea services (i.e. phase 2 only).
5Most services can be run locally in isolation while developing, however this is not documented here.
6
7There are two main ways of testing ea web services during development.
8
9The first is running the services on a banner cluster you own.
10This tests much more than the second option as kubernetes resources such as KCC resources are also tested.
11
12The second option is running the services locally directly on a development machine.
13This is what is in this document.
14
15**The following steps will break if multiple eagateway instances are connected to the same store cluster at the same time**
16E.g. If an eagateway service is running on a banner cluster simultaneously to running eagateway locally.
17
18## Prerequisites
19
20- Fully set up and working banner cluster
21- Fully set up and working store cluster.
22 This document does not outline steps to create PubSub resources, they must be created beforehand, e.g. through a real store cluster deployed against a banner cluster
23- Postgres db prepopulated with cluster and rules details. See [Database Setup](#database-setup)
24- GCP PubSub admin permissions or equivalent on the banner project (bellow steps require your user account, not a SA to have these permissions). Most teams will have their own GCP Banner Project to test against, e.g. `dev1-oblivion`
25- Edge API/BFF Endpoint
26 You will need an active NCR Edge user account configured on the Edge API.
27 Suggestion is to use your user account on dev1 `https://dev1.edge-preprod.dev/api/v2`
28
29
30## Environment
31
32EA Services should all use `godotenv` to allow specifying environment variables in a local `.env` file and loading during runtime.
33`.env` files are not loaded when running in production.
34The `.env` file should be created within the directory that contains the binary, e.g. for authservice use `cmd/sds/emergencyaccess/authservice/.env`.
35
36- All services should set
37
38 ```bash
39 APP_ENV=local-dev
40 GIN_MODE=debug
41 ```
42
43- Each service must run on a different port, set the `PORT` env var in each `.env` file.
44
45 ```bash
46 PORT=
47 ```
48
49- Rules engine, userservice and authservice require access to the DB. See [Database Setup](#database-setup)
50
51- Authservice requires access to userservice and rulesengine, they will be of the form `localhost:<PORT>`, where `<PORT>` is the value set in the respective `.env` files.
52
53 ```bash
54 EA_USER_SERVICE_HOST="localhost:9093"
55 EA_RULES_ENGINE_HOST="localhost:9092"
56 ```
57
58- Auth service needs access to an edge api server, suggestion is to use dev1
59
60 ```bash
61 EDGE_API="https://dev1.edge-preprod.dev/api/v2"
62 ```
63
64- Eagateway requires access to authservice
65 ```bash
66 EA_AUTH_SERVICE_HOST="localhost:9091"
67 ```
68
69## Database Setup
70
71GCP SQLInstance or standard postgres DB is required.
72If GCP SQLInstance you will likely need a sql proxy to access it. If standard postgres DB you will need to know the password.
73
74The DB must be prepopulated with all relevant data.
75This includes banner, cluster and terminal info, as well as emergency access specific data in the `oi_role_privileges`, `ea_rules`, `ea_rules_commands`, `ea_rules_default`, and `ea_rules_privileges` tables.
76For an example of how to set up a postgres db on the banner cluster, see https://github.com/ncr-swt-retail/edge-roadmap/issues/8650#issuecomment-1878952078, and the linked branch.
77
78You will need access to the database locally.
79The following steps document how to connect to a PostgresDB running as a pod on a k8s cluster.
80If you are using another DB type, such as a local database or SQL Instance,
81follow the standard connection steps for the database and fill in the `.env` file using the standard environment variables for database connections.
82
83Port-forward the database service to a local port:
84
85```
86kubectl port-forward -n postgres svc/postgres 5432:5432
87```
88
89Your services will need access to the db.
90If you are using env variables set the following environment variables.
91
92```bash
93DATABASE_HOST="localhost"
94DATABASE_PORT="5432"
95DATABASE_NAME=
96DATABASE_USERNAME=
97PGAPPNAME=
98DATABASE_PASSWORD=
99```
100
101`DATABASE_NAME`, `DATABASE_USERNAME` and `DATABASE_PASSWORD` should be known from when the db was created.
102
103`PGAPPNAME` should be set to a unique string per service, e.g. `PGAPPNAME=ea-authservice-<myuserid>`
104
105# Setup UserService
106
107Userservice requires mapping files to be created.
108Copy the test mapping files to the appropriate directory. Optionally update both files.
109
110```bash
111mkdir /etc/userservice
112cp pkg/sds/emergencyaccess/user/server/testdata/user-role.mapping /etc/userservice
113```
114
115# Running Services
116
117You may first need to authenticate with Google for eagateway to run correctly
118
119```bash
120gcloud auth application-default login
121```
122
123All services should be started in a different tab/run in background using the bash `&`.
124
125```bash
126just run cmd/sds/emergencyaccess/userservice
127just run cmd/sds/emergencyaccess/rulesengine
128just run cmd/sds/emergencyaccess/authservice
129just run cmd/sds/emergencyaccess/eagateway
130```
131
132# Running Remotecli
133
134Set EA Gateway host. Set the port to the value in the eagateway .env file
135
136```bash
137export RCLI_GATEWAY_HOST="http://localhost:9090/ea/"
138```
139
140```bash
141just run cmd/sds/emergencyaccess/remotecli
142```
143
144Connect with auth details and endpoint that was set up in authservice's `EDGE_API`, e.g.
145
146```
147Please enter the Edge API URL: https://dev1.edge-preprod.dev/api/v2
148```
149
150# Viewing Logs
151
152The web services should all log to stdout, which means the logs should be directly viewable on the terminal tab that the service is running in.
153
154> **_Tip_**: Run the services with `just run cmd/sds/emergencyaccess/<service> | jq -R '. as $line | try fromjson catch $line'` to automatically format any json output
155
156Remotecli logs are created in the bazel output directory.
157This is usually found at `./bazel-out/k8-fastbuild/bin/cmd/sds/emergencyaccess/remotecli/remotecli_/remotecli.runfiles/_main/remotecli.log`
158
159> **_Tip_**: Add the following function to your bashrc.
160> ```bash
161> rclilog() {
162> cat "${HOME}/edge/edge-infra/bazel-out/k8-fastbuild/bin/cmd/sds/emergencyaccess/remotecli/remotecli_/remotecli.runfiles/_main/remotecli.log" | jq -C '.' | less +G -R -N
163> }
164> ```
165>
166> Then run `rclilog` to automatically format and open the most recent log
View as plain text