This document describes how to run the CaeNDR project locally.

FIRST, please perform all required setup steps in "Getting Started"! If you cannot get something to run here, please make sure it's not a setup problem!

There are a few components of the site you might want / need to run:

• For the site to work locally, you MUST have done all of the following:
  • Have the database proxy running
  • Have the two required env vars defined in whichever terminal is running the site
  • Be logged in with GCP
• When you're done running locally, we recommend you stop the database proxy. Instructions are below.

The following two environment variables must be set to run the site locally:

Note: Make sure they're defined in the terminal / thread / etc you're using to run the site. It's very easy to pop open a new window, switch over to VSCode, etc. and forget that you haven't defined them in the new thread yet. (I say this because I've done it. Many times.)

Run the following in your terminal window:

export GOOGLE_APPLICATION_CREDENTIALS=~/.gcp/{ NAME_OF_THE_SERVICE_ACCOUNT_FILE }.json
export ENV=development

You may need to do this for each window for multiple apps.

The Google Cloud SQL proxy serves as your local connection to the Google Cloud Platform SQL instance(s) that hold the bulk of CaeNDR's scientific data. It MUST be running in the background in order for the local web app (i.e. the CaeNDR site) to work, as well as a few of the other modules.

NOTE: Once you're done working on the local site, we recommend stopping the proxy. (Your PC probably won't explode if you don't, but it is best practice.)

1. Before starting the proxy, make sure to set the environment variables, as outlined above. (link)

2. Open one terminal window and navigate to the site module. (For historical reasons, you do have to use site, not site-v2.)

   cd src/modules/site

3. Use make to set up the directory and start the proxy.

   make clean
   make configure
   make cloud-sql-proxy-start

4. Check that the cloud-sql-proxy docker container is running:

   docker ps

   The result should look something like the following:

   CONTAINER ID   IMAGE                                            COMMAND                  CREATED       STATUS        PORTS                    NAMES
   9413d4f448f0   gcr.io/cloudsql-docker/gce-proxy:1.28.1-alpine   "/cloud_sql_proxy -i…"   3 weeks ago   Up 23 hours   0.0.0.0:5432->5432/tcp   caendr-cloud-sql-proxy-1
   

   Please note that most of these values, in particular the CONTAINER_ID, will be different on your machine. (Also, you may have other Docker containers running on your machine - we're specifically checking for the caendr-cloud-sql-proxy container.)

5. Keep this docker container running while running the site below.

Note: As a fallback, the SQL proxy start command looks something like this in the background:

./cloud_sql_proxy -instances=${GOOGLE_CLOUD_PROJECT_ID}:${GOOGLE_CLOUD_REGION}:${MODULE_DB_OPERATIONS_INSTANCE_NAME} -dir=/cloudsql &

However, we do NOT recommend running this directly, without at least attempting to use the make command first.

Once you are done working on the site and no longer need the database, we recommend you close the connection.

1. Run the stop command with make.

   make cloud-sql-proxy-stop

2. Check to make sure this stopped the container. You can do this by e.g. checking for it in the list of running containers:

   docker ps

   If the container stopped, you should not see it listed.

3. If this did not stop the container, you can kill it manually with Docker. First, find the container ID (first column) in the output of the previous step, which should look something like:

   CONTAINER ID   IMAGE                                            COMMAND                  CREATED          STATUS          PORTS                    NAMES
   75ef941c1e64   gcr.io/cloudsql-docker/gce-proxy:1.28.1-alpine   "/cloud_sql_proxy -i…"   29 minutes ago   Up 29 minutes   0.0.0.0:5432->5432/tcp   caendr-cloud-sql-proxy-1
   

   In this case, the container ID is 75ef941c1e64, in the first column.

4. Stop the container manually, using the container ID. In our example, this looks like:

   docker kill 75ef941c1e64

5. Check docker ps again as in step (2), to make sure the kill command worked.

To run the CaeNDR web app locally, we recommend using VSCode. To install and set up, see Getting Started.

1. Make sure the Database Proxy is running (see steps above).

2. Open a new terminal window. (This will need to be a different window than the one created to run the database proxy.)

3. Set the required environment variables in this new terminal (see steps above).

4. Navigate to the site-v2 module.

   cd src/modules/site-v2
   

5. Use make to configure your local copy.

   make configure
   make dot-env
   make venv
   

6. Open Visual Studio Code from the terminal. Note that this will open the app at the root of the project, with the proper environment variables set.

   code ../../..
   

7. From the DEBUG->List of options, select "Run Site-v2 (requires a local Postgres instance or cloud-sql-proxy)" and click "Play".

This version is a bit jankier, and we don't necessarily recommend it, but it does (usually) work, and it lets you go through VSCode directly. The main problem with going through VSCode is setting the required environment variables -- if you open through Terminal, they're copied over to all threads spawned by VSCode, but if you open the app directly, they're not set. Turns out though, you can splice them into the running command line...

We don't necessarily recommend going this route if you can avoid it, but if you have VSCode open already and the environment variables are undefined, this will let you set them without closing & re-opening.

1. Make sure the Database Proxy is running (see steps above).

2. Open VSCode as normal, and open the root project folder.

3. From the DEBUG->List of options, select "Run Site-v2 (requires a local Postgres instance or cloud-sql-proxy)" and click "Play". Once this spawns a new terminal, click "Stop".

4. Set the environment variables in the new VSCode terminal window that was spawned (see steps above).

5. Click "Play" again.

Each individual module is a bit different, but the general pattern to run them is as follows:

1. Make sure the Database Proxy is running (see steps above), if the module you want to run requires it. If you're not sure, it won't hurt to run it just in case.

2. Set the required environment variables (see steps above).

3. Set a few extra environment variables to configure the module:

   export MODULE_DB_OPERATIONS_CONNECTION_TYPE=localhost
   export MODULE_DB_TIMEOUT=3

4. Navigate to the module's src directory, and use make to run it:

   make run