DEV Community

Aldorax
Aldorax

Posted on

My Trial by Fire: A Complete Chronicle of Setting Up OSO as a PLDG Cohort-3 Newcomer

#blockchain #web3 #linux #opensource

Prologue: Joining the PLDG Family

As I received my acceptance into Protocol Labs Developer Guild's Cohort-3, a mix of excitement and nervous energy coursed through me. Having chosen Open Source Observer (OSO) as one of my focus projects, I was eager to dive in. Little did I know that simply setting up the development environment would become an epic odyssey filled with technical challenges, small victories, and valuable lessons.

Chapter 1: The Installation Wars

The UV Dilemma

The documentation casually mentioned:

"Install UV: The modern Python package manager OSO uses"

First Attempt:

pip install uv
Enter fullscreen mode Exit fullscreen mode

Result: The command ran without errors, but something felt off. When I tried using UV, I encountered strange permission errors and version conflicts.

The Investigation:

After two hours (just kidding—I actually just clicked the link in the OSO documentation for UV), I discovered the official UV installation guide, which revealed the proper method:

curl -LsSf https://astral.sh/uv/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

The Moment of Truth: The installation script scrolled through my terminal, each line loading with anticipation. Would it work this time? The final "Installation complete" message brought immense relief.

Why This Matters:

UV is a relatively new tool (launched in 2024) that's rapidly becoming the standard for Python projects. Its speed and reliability improvements over traditional pip make it worth the initial setup hassle.

The DuckDB Installation Saga

The next prerequisite was DuckDB, described as "SQLite for analytics." The installation seemed straightforward:

brew install duckdb  # For macOS
Enter fullscreen mode Exit fullscreen mode

But on my Linux machine:

sudo apt-get install duckdb
Enter fullscreen mode Exit fullscreen mode

Lesson Learned: Always check the official DuckDB installation docs for your specific OS—especially when dealing with tools you've never used before.

Chapter 2: The Missing Setup Revelation

Now I had to run:

uv sync
source .venv/bin/activate
Enter fullscreen mode Exit fullscreen mode

It worked! —At least, that's what I thought until I ran:

uv run oso local sqlmesh-test --duckdb plan dev --start '1 week' --end now
Enter fullscreen mode Exit fullscreen mode

The Crash:

ModuleNotFoundError: No module named 'metrics_service'
Enter fullscreen mode Exit fullscreen mode

The Panic:

I spent hours (okay, less than one hour):

  1. Checking Python versions
  2. Verifying virtual environments
  3. Re-reading the setup guide
  4. Scouring GitHub issues for similar problems

The Breakthrough:

While examining the project structure, I noticed the pyproject.toml file. Aha! The project needed to be installed in development mode:

uv pip install -e .
Enter fullscreen mode Exit fullscreen mode

The Magic: The -e flag stands for "editable" mode, meaning:

  • Changes to source files are immediately available
  • All dependencies are properly linked
  • The package is recognized system-wide

Why This Wasn't Obvious:

This step is second nature to experienced Python developers but rarely explained in project setup guides. For newcomers, it's a critical missing piece.

Chapter 3: The GCP Initiation—Credit Cards and Courage

When I first signed up for Google Cloud Platform (because OSO needed it), I approached it with the reckless abandon of a college student signing up for their first credit card. The process went something like this:

  1. The Innocent Beginning: "Oh look, I can just use my Google account! How convenient!"
  2. The Moment of Truth: "Add a payment method to continue" stared back at me like a bouncer at an exclusive club.
  3. The Rationalization: "Well, they're offering $300 in free credit... that's basically free money, right?"

At this point, I had two options:

  • Option A: Carefully research GCP pricing, set up budget alerts, and monitor usage like a hawk
  • Option B: YOLO it and see what happens

Guess which path I chose?

My Actual Thought Process:

"Ha! Let's see how far I can stretch this $300! If I accidentally burn through it all in one glorious inferno of cloud computing, that'll make a great story! (Note to readers: Please don't actually do this—we'll get to the responsible part later.)"

I clicked through the signup with the enthusiasm of someone who's never received an unexpected cloud bill, added my card (while mentally calculating how many months of ramen $300 could buy me as a backup plan), and was immediately rewarded with my shiny new GCP playground.

The CLI Tool Tango

With my new GCP account ready, I turned to the documentation like a pirate consulting a treasure map. The official gcloud CLI docs became my bible as I ran commands with the confidence of someone who absolutely knew what they were doing (I didn't).

Installing gcloud CLI

The first command failed spectacularly:

gcloud init
zsh: command not found: gcloud
Enter fullscreen mode Exit fullscreen mode

The Installation Process:

  1. Downloaded the SDK: 
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
Enter fullscreen mode Exit fullscreen mode
  1. Extracted and installed: 
tar -xzf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh --quiet
Enter fullscreen mode Exit fullscreen mode
  1. Updated my shell configuration: 
echo '# Google Cloud SDK' >> ~/.zshrc
echo 'source /path/to/google-cloud-sdk/path.zsh.inc' >> ~/.zshrc
echo 'source /path/to/google-cloud-sdk/completion.zsh.inc' >> ~/.zshrc
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode

The Authentication Maze

Running gcloud init launched an interactive wizard:

  1. Account Selection:

    • Opened a browser window for signing in
    • Asked if I trusted gcloud—I said yes, and boom! Done, back to the terminal!

  2. Project Configuration:

    The same command prompted me with:

Pick cloud project to use:  
 [1] *****  
 [2] ****  
 [3] Enter a project ID  
 [4] Create a new project  
Please enter numeric choice or text value (must exactly match list item):  4
Enter fullscreen mode Exit fullscreen mode

I entered aldo-pldg-oso, and then:

Your current project has been set to: [aldo-pldg-oso].  

Not setting default zone/region (this feature makes it easier to use  
[gcloud compute] by setting an appropriate default value for the  
--zone and --region flag).  
See https://cloud.google.com/compute/docs/gcloud-compute section on how to set  
default compute region and zone manually. If you would like [gcloud init] to be  
able to do this for you the next time you run it, make sure the  
Compute Engine API is enabled for your project on the  
https://console.developers.google.com/apis page.  

Created a default .boto configuration file at [/home/aldy/.boto]. See this file and  
[https://cloud.google.com/storage/docs/gsutil/commands/config] for more  
information about configuring Google Cloud Storage.  
The Google Cloud CLI is configured and ready to use!
Enter fullscreen mode Exit fullscreen mode
  1. Region Selection: Now I had to make sure the project was set: 
gcloud config get-value project  # Should return "aldo-pldg-oso"
Enter fullscreen mode Exit fullscreen mode

It returned:

aldo-pldg-oso
Enter fullscreen mode Exit fullscreen mode

Next, I needed to set the project ID in my shell for easy access:

export GOOGLE_PROJECT_ID="aldo-pldg-oso"
Enter fullscreen mode Exit fullscreen mode

Critical Step:

gcloud auth application-default login
Enter fullscreen mode Exit fullscreen mode

This created credentials at ~/.config/gcloud/application_default_credentials.json—the golden ticket for local development.

I also exported it for good measure:

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
Enter fullscreen mode Exit fullscreen mode

Chapter 4: Service Account Security Theater

Creating the Service Account 

gcloud iam service-accounts create oso-local-dev \
  --display-name="OSO Local Development Account"
Enter fullscreen mode Exit fullscreen mode

Permission Assignment:

gcloud projects add-iam-policy-binding aldo-pldg-oso \
  --member="serviceAccount:oso-local-dev@aldo-pldg-oso.iam.gserviceaccount.com" \
  --role="roles/editor"
Enter fullscreen mode Exit fullscreen mode

Generating the Key File 

gcloud iam service-accounts keys create ~/oso-service-account-key.json \
  --iam-account=oso-local-dev@aldo-pldg-oso.iam.gserviceaccount.com
Enter fullscreen mode Exit fullscreen mode

Handling the Key:

Set the environment variable:

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/oso-service-account-key.json"
Enter fullscreen mode Exit fullscreen mode

Chapter 5: The BigQuery Showdown

Enabling the API

After all this, I tried running OSO again but got this frustrating error:

403 BigQuery API has not been used in project ***** before or it is disabled.
Enter fullscreen mode Exit fullscreen mode

The Fix:

gcloud services enable bigquery.googleapis.com
Enter fullscreen mode Exit fullscreen mode

Verification:

gcloud services list --enabled | grep bigquery
Enter fullscreen mode Exit fullscreen mode

Which returned:

bigquery.googleapis.com             BigQuery API  
bigqueryconnection.googleapis.com   BigQuery Connection API  
bigquerydatapolicy.googleapis.com   BigQuery Data Policy API  
bigquerymigration.googleapis.com    BigQuery Migration API  
bigqueryreservation.googleapis.com  BigQuery Reservation API  
bigquerystorage.googleapis.com      BigQuery Storage API
Enter fullscreen mode Exit fullscreen mode

Testing the Connection 

bq ls
Enter fullscreen mode Exit fullscreen mode

First Attempt: Success!
Enter fullscreen mode Exit fullscreen mode

The empty result was beautiful—it meant everything was working.

Chapter 6: Final Victory

With all pieces in place, the moment of truth:

oso local initialize
Enter fullscreen mode Exit fullscreen mode

The output scrolled by:

2025-06-29T12:23:51 - INFO - Loading opensource-observer.farcaster.profiles...  
2025-06-29T12:23:53 - INFO - Initialization complete!
Enter fullscreen mode Exit fullscreen mode

Celebration: I may have done a little victory dance at this point.

Epilogue: Lessons for Future Cohort Members

  1. Documentation is a Starting Point: Expect to supplement official guides with your own research.
  2. Cloud Setup is Complex: Budget significant time for authentication and service configuration.
  3. Error Messages are Gold: Learn to read them carefully—they often contain the solution.
  4. Ask Early: The PLDG community is incredibly supportive—don't struggle alone.
  5. Document Your Journey: Your struggles will help the next cohort member.

Resources That Saved Me

  1. UV Documentation - Essential for understanding this new package manager.
  2. DuckDB Installation Guide - OS-specific instructions.
  3. Google Cloud Quickstart - Great for understanding core concepts.
  4. Python Packaging Guide - Explains editable installs and more.

Final Thoughts

This setup journey, while challenging, taught me more about modern development practices than any tutorial could have. The combination of new tools (UV), specialized databases (DuckDB), and cloud services (GCP) represents exactly the kind of real-world complexity we need to master as open-source contributors.

To my fellow cohort members: embrace the struggle. Each error resolved is a lesson learned, and every working setup is a victory worth celebrating. See you in the commits!

Top comments (0)