From bae39ecf31f91eb1a9da4f27aa6eeaab40558dd7 Mon Sep 17 00:00:00 2001
From: Gabriele Bozzola <gbozzola@caltech.edu>
Date: Sat, 3 Aug 2024 13:04:45 -0700
Subject: [PATCH] Add docs on ssh tunnelling

[skip ci]
---
 ClimaExplorer/explorer.jl |  9 ---------
 docs/src/explorer.md      | 31 +++++++++++++++++++++++++------
 2 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/ClimaExplorer/explorer.jl b/ClimaExplorer/explorer.jl
index 4733ea61..00b523d8 100644
--- a/ClimaExplorer/explorer.jl
+++ b/ClimaExplorer/explorer.jl
@@ -10,15 +10,6 @@ port = 8080
 server = Server(IPa, port; proxy_url = "http://localhost:9384")
 
 app = ClimaExplorer.BonitoApp(path)
-
 route!(server, "/" => app)
 println(server)
 wait(server)
-
-# connect to calhpc via
-# ssh -L 9384:localhost:8080 calhpc
-# (assuming calphc is configured as [USER]@[SSH_SERVER]
-
-# run this script
-# app will be on http://localhost:9384/atmos
-# on the Caltech network
diff --git a/docs/src/explorer.md b/docs/src/explorer.md
index e08d6679..9266a387 100644
--- a/docs/src/explorer.md
+++ b/docs/src/explorer.md
@@ -8,13 +8,13 @@ local server and dynamically serve plots.
 How to install
 ===============
 
-To install `ClimaExplorer`, first clone the `ClimaAnalysis.jl` repo
+To install `ClimaExplorer`, first clone the `ClimaAnalysis.jl` repository
 ```sh
 git clone https://github.com/CliMA/ClimaAnalysis.jl.git
 ```
 Then, instantiate the `climaexplorer` environment
 ```sh
-julia --project=ClimaAnalysis.jl/climaexplorer -e 'using Pkg; Pkg.instantiate()'
+julia --project=ClimaAnalysis.jl/ClimaExplorer -e 'using Pkg; Pkg.instantiate()'
 ```
 
 How to use
@@ -22,17 +22,19 @@ How to use
 
 Once you installed `ClimaExplorer`, you can start the server with
 ```sh
-julia --project=ClimaAnalysis.jl/climaexplorer ClimaAnalysis.jl/climaexplorer/explorer.jl PATH_OF_OUTPUT 
+julia --project=ClimaAnalysis.jl/climaExplorer ClimaAnalysis.jl/ClimaExplorer/explorer.jl 
 ```
-where `PATH_OF_OUTPUT` is the path where the output files live.
-The first time you do so, this will take a little while.
+This might take a while.
+
+You can also pass a path as an argument to `explorer.jl`. This will start `ClimaExplorer` with  
+that folder (by default, the current working directory is used).
 
 If everything went correctly, you should see a message like
 ```
 Server:
   isrunning: true
   listen_url: http://localhost:8080
-  online_url: http://localhost:8080
+  online_url: http://localhost:9384
   http routes: 1
     / => App
   websocket routes: 0
@@ -40,3 +42,20 @@ Server:
 This means that the server has started. Visit `http://localhost:8080` to start
 inspecting the output. Note that the port number `8080` might be different.
 To close the server, press `Ctrl-C`.
+
+How to use on remote clusters
+=============================
+
+Often data resides on remote clusters. You can run `ClimaExplorer` on the
+machine where the data lives and use an ssh tunnel to access the server from
+your computer.
+
+To do so, first start the server on the remote cluster (as described above). 
+Next, on your local machine, forward the remote port:
+```bash
+ssh -f username@host -L 9384:localhost:8080 -N
+```
+instead of `username@host`, put your `usarename` and `hostname` (e.g.,
+`pippo@login.hpc.caltech.edu`)
+
+Next, open your browser and access `ClimaExplorer` visiting `localhost:9394`.