📘 GCP Workstation Setup Guide

Advanced Acoustics – Scientific Integration (AA-SI)

A friendly, step-by-step guide to getting your Google Cloud workstation ready for the AA-SI toolset.

---

👋 Welcome!

This guide will walk you through setting up a Google Cloud Platform (GCP) Workstation for use with the AA-SI (Advanced Acoustics – Scientific Integration) toolset. Whether this is your first cloud environment or just a refresher, you're in the right place — there are screenshots along the way and helpful tips to keep you on track.

---

📑 Table of Contents

• Before You Begin
• GCP Workstation Configuration
• Environment Initialization
• Using the AA-SI Toolset
• Disclaimer

---

✅ Before You Begin

Before starting, please make sure you have:

1. ✉️ A NOAA Gmail account that is active and accessible.
2. 🔐 Authorization to deploy GCP Workstations hosted by NMFS – Office of Science and Technology.

💡 Don't have access yet? No worries — start here: github.com/enterprises/noaa-nmfs

---

☁️ GCP Workstation Configuration

Step 1 — Navigate to the GCP Workstations Console

Open your browser and head to: 🔗 console.cloud.google.com/workstations/overview

---

Step 2 — Create a Workstation

Use the interface to configure and deploy a new workstation.

---

Step 3 — Choose a Name, Display Name, and JupyterLab Configuration

Pick something descriptive so you can easily find your workstation later.

---

Step 4 — Launch the Workstation

Once your workstation is created, go ahead and launch it.

---

Step 5 — Open the Terminal

Start a terminal session inside your running GCP workstation — this is where the rest of the setup happens.

---

⚙️ Environment Initialization

Step 1 — Run the Initialization Script

This will download and run the AA-SI setup script, set permissions, and activate the Python virtual environment.

Paste the following into your terminal:

cd && \
sudo rm -f init.sh && \
sudo wget https://raw.githubusercontent.com/nmfs-ost/AA-SI_GPCSetup/main/init.sh && \
sudo chmod +x init.sh && \
./init.sh && \
cd ~ && \
source venv313/bin/activate

🐍 Why venv313? Python 3.13 is the version we've standardized on for the AA-SI toolset.

---

Step 2 — Authenticate with GCP

Next, sign in with your NOAA credentials and point gcloud at the AA-SI project:

gcloud auth application-default login && \
gcloud config set account {{ACCOUNT}} && \
gcloud config set project ggn-nmfs-aa-prod-1

A link will appear in the terminal — follow it to complete the Google sign-in flow with your NOAA account.

📌 About the placeholders

• {{ACCOUNT}} is typically your NOAA email. If you're unsure or run into trouble with this line, try running just the gcloud auth application-default login command on its own — the browser sign-in often handles account selection for you.
• ggn-nmfs-aa-prod-1 is the shared AA-SI Project ID. Leave it as written.

⏰ Session timed out? Just run the same commands again to re-authenticate.

---

Step 3 — Reactivating the Environment Later

Any time you return to your workstation, jump back into the AA-SI environment with:

source venv313/bin/activate

---

🧰 Using the AA-SI Toolset

Explore Available Tools

Once your environment is active, you can explore the full suite of AA-SI functionalities by running:

aa-find

🎉 That's it — you're ready to start working!

---

📜 Disclaimer

This repository is a scientific product and is not official communication of the National Oceanic and Atmospheric Administration, or the United States Department of Commerce. All NOAA GitHub project code is provided on an 'as is' basis and the user assumes responsibility for its use. Any claims against the Department of Commerce or its bureaus stemming from the use of this GitHub project will be governed by all applicable Federal law. Reference to specific commercial products, processes, or services by service mark, trademark, manufacturer, or otherwise does not imply endorsement or favoring by the Department of Commerce. Use of DOC seals or logos shall not suggest endorsement by DOC or the U.S. Government.

---

Made with 🌊 by NOAA NMFS – Office of Science and Technology