SSH Tunnels

We don't necessarily have to use SSH tunnels with our Flask apps, but we often will. This short reading explains why and how. If you're just looking for a reminder, you can skip to the conclusion

Why SSH Tunnels¶

Why is this necessary. Well, it's not always necessary, but it is often necessary, and once you've done it a few times, it'll become easy and routine, and since it solves a couple of common problems, it's good to know how to do it.

What are those two problems? The campus firewall and browsers that want to use HTTPS.

1. The campus firewall

The ports that our Flask apps run on are not visible outside the campus firewall, so if our laptop is outside the campus firewall, you necessarily must use an SSH tunnel. How could you be outside the campus firewall?

• you're working from home, maybe over a break
• you're working from MIT or Babson or Olin, where you're taking a cross-registered class,
• you're working at a coffee shop or other off-campus location
• etc.

2. Avoiding SSL connections

Many browsers want to convert http:// URLs into https:// URLs, because we should all be using secure, encrypted SSL connections. But our development versions of Flask don't have encrypted SSL connections, so that's a problem.

SSH Tunnels can solve both of those problems because

• The SSH tunnel can get through the campus firewall, and
• The URL is localhost:8080 which the browser doesn't try to convert to https://

So, I suggest getting in the habit of using SSH Tunnels. Once you've done it a couple of times, it becomes easy and routine.

High Level View¶

There are three steps. Let's look at them conceptually, first:

1. Run your Flask App on Tempest;
2. Start the SSH tunnel on your laptop;
3. Connect to the Flask App from your browser.

The first two steps are setup steps that you'll only do once each session of work on your app. The last is part of routine coding and debugging, so you might do it many times during a session.

You can actually do the two setup steps in either order, but I'm going to describe them in the order I've given.

Adapting My Examples¶

You won't just be able to copy my commands, because they depend on the account (username) that we are using, and your account is different from mine. So, you'll have to fill in your own values. Here's a quick table of the idea, my example value, and how you can find out your value.

The last column is a Unix command that you can run on Tempest, the CS department server (also known as cs.wellesley.edu).

You can copy/paste the following commands into your VS Code terminal:

whoami
id -u

Step 1. Run your Flask App¶

To run your Flask App, you'll need to do the following:

• Launch VS Code
• Login to your Tempest account
• Activate your virtual environment
• Run the appropriate app.py (or equivalent file).

That last step will give you output like this:

(venv) [cs304guest@tempest people_app]$ python app.py 
 * Serving Flask app 'app' (lazy loading)
 * Environment: production
   WARNING: This is a development server. Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Debug mode: on
 * Running on all addresses.
   WARNING: This is a development server. Do not use it in a production deployment.
 * Running on http://149.130.15.5:8299/ (Press CTRL+C to quit)

Take note of the first line, where we run the app:

(venv) [cs304guest@tempest people_app]$ python app.py 

The (venv) in the prompt reminds us that we did activate our virtual environment. The cs304guest@tempest part of the prompt reminds us what account we are logged into; it's our username. Yours will be different; it'll be your account on the CS server. See adapting my examples.

Also take note of that last line, http://149.130.15.5:8299/. The four digit number after the colon tells you the port that your app is running on (inside the campus firewall). Our Flask apps will be running on a port that corresponds to our UID, so yours will not be 8299. See adapting my examples.

Step 2: Start your SSH Tunnel¶

To start your SSH tunnel, you'll need to start at terminal on your laptop (not on the CS server). So you will not use VS Code. (A common error is to use VS Code, as you did above to start your application, and then start the SSH tunnel on the server; that won't work.)

Mac Users

If your laptop is a Mac, use the terminal application. You can find that under "Applications > Utilities" or use the Spotlight Search and search for "terminal".

Windows Users¶

If your laptop is a Windows machine, you need the "command prompt" (or Power Shell) application. Here are ten ways to open the command prompt.

Start the SSH Tunnel

Once you've started a terminal, you just need to adapt the following SSH command:

ssh -L 8080:localhost:8299 cs304guest@cs.wellesley.edu

Remember, you'll have to substitute your own UID/PORT for the 8299 and your own username for the cs304guest.

Step 3: Connect from your Browser¶

Once the app is running (step 1) and the SSH tunnel is set up (step 2), you can then go to your browser and open the following URL:

http://localhost:8080/

Yes, that's an unencrypted HTTP connection, but your browser should be okay with it, because it's connecting to itself (localhost).

Conclusion¶

That's it! Three pretty simple steps:

• run the app: python app.py
• set up the tunnel: ssh -L 8080:localhost:port username@cs.wellesley.edu
• view the app: http://localhost:8080/

(Well, they're simple once you've done them a couple of times.)

If you'd like to see a demo, here's a video demonstration

Remember, though, that you'll have to customize those steps to your username, port, and the app you are running.