Welcome to the Astronomy on Bluesky development team! 🎉

This guide is your starting point for getting up to speed with the project. It provides all the resources, tools, and information you need to hit the ground running.

System Architecture:

Follow these steps to get started:

1. Request Access: Ensure you have access to the required resources.
   • Bluesky account
   • Added to github Astronomy on Bluesky org
   • Added to Bluesky Devs Discord
2. Set Up Your Environment: Follow the Development Environment Setup instructions to configure your local machine.
3. Explore the Codebase: Start with the Repository Structure section for an overview of the code organization.
4. Start Your First Task: Pick a First Task to familiarize yourself with the project and workflow.

1. Install the uv python package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository you'd like to work on - either with git:

git clone <repo_url>

or the GitHub CLI:

gh repo clone bluesky-astronomy/<repo_name>

3. Navigate into the repo and initialize a virtual environment with uv:

uv sync

4. Install & start PostgreSQL

Many services require a running PostgreSQL development database to run locally. Detailed instructions are in this file. We also recommend installing pgAdmin to make managing local databases much easier.

Make sure to start the PostgreSQL image every time you work on the project with sudo docker start AstroskyDB.

You will also need to download a copy of the development database - for now: ask Emily. (As of December 2025, we're hoping to improve this step soon - sorry!)

Once you download the dev database, you can load it to your (running) Docker container with

psql -h localhost -U postgres devdb < devdb.sql

replacing -U with your user (if changed) assuming that you have a PostgreSQL client installed on your system. (There may also be a way to do this step with pgAdmin.)

5. Set up relevant environment variables

Required environment variables for each project are/will be documented in the readme file of every repository.

As a hint, you could use a setup like

ASTROFEED_PRODUCTION=0
ASTROFEED_POSTGRES=0
BLUESKY_DATABASE="postgres://<your_db_username>:<your_db_password>@localhost:5432/<your_db_name>?ssl-mode=REQUIRED"
DEBUG_ENABLED=1

1. Install npm

We recommend first installing nvm to manage node.js installs. Then, install the latest LTS release of npm with

nvm install --lts

nvm use --lts

2. Install required dependencies

Instructions may depend on the project, but this is usually as simple as doing npm install in the folder.

3. Start development server

The following npm commands are useful:

• npm run dev: runs a development copy of the server locally.
• npm run build: performs a test build of the site/app. Useful to test build pipeline.
• npm run preview: previews the site/app locally from build artifacts. Useful to test build pipeline.

The Astronomy on Bluesky project consists of the following (main) repositories:

• Code Style:
  • For now, recommend following community-supported standards and best practices for each language. For example:
    • Python: PEP 8 -- Style Guide for Python Code
    • Python: Run code through Ruff
    • Python: Usage of Type Hints on variable definition. For example:
      • num_files: int
      • user_name: str
    • JavaScript/Typescript: Airbnb style guide
• Branching Strategy:
  • Use the feature-, bugfix-, hotfix-, and chore- prefixes for branches.
  • Main branch: main.
  • The main branch has branch protections on most repositories (see above table.) Commits to main will require approval.
• Code Reviews:
  • All code must go through a pull request (PR) process.
  • Assign at least one reviewer.
• Testing:
  • Unit tests are required (where possible) for all new features.
  • On the team, Vince has the most experience with setting up unit tests in the astronomy-feeds repo.
  • Run tests locally before submitting a PR.
• CI/CD Pipeline:
  • More coming soon! For now, the astronomy-feeds repo is checked for style with ruff on all PRs.

• GitHub org that all code lives in
• Development plan (is always the pinned issue)
• Our website

• Docs for the Python SDK
• Official protocol docs
• Bluesky's source code
• A nice introductory talk about AT Protocol
• An amazing flowchart of the AT Protocol's structure

• peewee, our database ORM
• Svelte/SvelteKit, our frontend framework of choice for web apps

• Bluesky handle debug tool (can also look up DIDs)
• Explore the records on any Bluesky PDS
• Clearsky search tool (can look up various things)
• Look up different AT Protocol lexicons
• edavis.dev's charts of Bluesky activity
• Jaz's stats page
• Searchable list of all firehose commits (down as of 22nd Nov. 2024)