Skip to content

Latest commit

 

History

History
112 lines (78 loc) · 4.5 KB

standalone_instance.md

File metadata and controls

112 lines (78 loc) · 4.5 KB
Raw

Simple standalone local test/evaluation/development instance

Note that all deployment strategies below require the use of Docker.

Architecture

Architecture diagram for running local processes

When the simple standalone deployment below is used, it will construct a DSS sandbox environment consisting of:

  • A DSS instance, consisting of:
    • A single CockroachDB node running in insecure mode via docker, communicating on port 26257 internally and exposing a web admin console on port 8080 externally
    • gRPC backend listening by default on port 8081 internally, configured to
      • Connect to a CockroachDB node (implicitly port 26257)
      • Validate access tokens with the auth2.pem public key
      • Expect access tokens to specify an aud of localhost
    • HTTPS gateway listening on port 8082 externally and directing requests translated into gRPC to port 8081 internally
  • A Dummy OAuth server exposing an endpoint at http://localhost:8085/token externally to generate dummy JWT access tokens that validate against the auth2.pem public key

Prerequisites

Run

Simply execute ./run_locally.sh. This will build the required Docker images if necessary and then construct the system described above.

When this system is active (log messages stop being generated), the following endpoints will be available:

In a different window, run ./check_dss.sh to run a demonstration RID query on the system. The expected output is an empty list of ISAs (no ISAs have been announced).

To perform more complicated actions manually, see the Postman collection in this folder (use with Postman).

To stop the system, just press ctrl-c or cmd-c.

Debugging Mode

run_locally.sh can also run in debugging mode, which enables debugging the gRPC backend code line by line with your favorite IDE. It is a very straightforward process with just 2 steps:

Step 1

Run run_locally.sh debug, we will see the local-dss-grpc-backend starts with the DEBUG MODE: on, and the API server is listening at port : 4000.

  • local-dss-grpc-backend_1 | Debug Mode: on
  • local-dss-scd-bootstrapper_1 | Allowing time for CRDB node to come up...
  • local-dss-grpc-backend_1 | API server listening at: [::]:4000

Step 2 (One Time Effort)

Add a remote debug configuration with your favorite IDE. Here we use IntelliJ / GoLand as an example:

  • Click Edit Configuration in the dropdown list right next to the 'bug' icon.

    Add_remote_configuration_1

  • Add a new Go Remote configuration.

    Add_remote_configuration_2

  • Set the Host as localhost and Port as 4000, click OK.

    Add_remote_configuration_3

Enjoy!

All Set, let's start the debug configuration created in the step 1 and we are able to debug any request sent to the local DSS endpoints hosted at localhost:8082.

  • Drop breakpoints and diagnose in real time

    Debug_result_1

  • Access variables

    Debug_result_2

Advanced

run_locally.sh is a thin wrapper around a docker-compose command and all the docker-compose verbs may be passed to run_locally.sh. The default verb is up, but, e.g., the system can be removed entirely with run_locally.sh down. See all docker-compose verbs here.

Specifically, after changing code for one or more of the services, make sure to execute run_locally.sh build to incorporate the new changes into the local deployment images. Make sure to restart the local system to reflect changes to the local deployment images.

Troubleshooting

If one or more of the necessary ports are not available, identify the process using a port with lsof -i tcp:8080.