Skip to content
Astromesh Astromesh

Quick Start

Get from zero to a production Astromesh stack on GCP in under 10 minutes.

Prerequisites:

  • Python 3.12+
  • Terraform installed and on PATH
  • A GCP project with billing enabled
  • gcloud CLI authenticated (gcloud auth login)

  1. Install Orbit

    Section titled “Install Orbit”

    Install astromesh-orbit with the GCP provider extra:

    Terminal window
    pip install astromesh-orbit[gcp]

    Verify the installation:

    Terminal window
    astromeshctl orbit --help
    Usage: astromeshctl orbit [OPTIONS] COMMAND [ARGS]...
    

    Cloud-native deployment for Astromesh.
    

    Commands:
      init     Initialize orbit.yaml with an interactive wizard
      plan     Preview infrastructure changes
      apply    Provision the full Astromesh stack
      status   Show deployment status
      destroy  Tear down all provisioned resources
      eject    Export standalone Terraform files

  2. Initialize Configuration

    Section titled “Initialize Configuration”

    Run the interactive wizard to generate your orbit.yaml:

    Terminal window
    astromeshctl orbit init --provider gcp

    The wizard walks you through the key decisions:

    ╭─ Astromesh Orbit ─────────────────────────────────╮
    │                                                    │
    │  Welcome! Let's configure your deployment.         │
    │                                                    │
    ╰────────────────────────────────────────────────────╯
    

    ? GCP Project ID: my-project-123
    ? Region: us-central1
    ? Deployment preset:
      ❯ Starter (~$30/mo) — 1 instance, db-f1-micro, 1GB cache
        Pro (~$150/mo) — auto-scaling, db-g1-small with HA, 4GB cache
        Custom — configure everything manually
    ? Environment: production
    

    ✓ Generated orbit.yaml
    ✓ Added .orbit/ to .gitignore

    For a quick start, use the --preset flag to skip the wizard:

    Terminal window
    astromeshctl orbit init --provider gcp --preset starter

  3. Preview Changes

    Section titled “Preview Changes”

    Run orbit plan to validate your configuration and preview what Terraform will create:

    Terminal window
    astromeshctl orbit plan

    Orbit validates your GCP project, checks permissions, and generates a Terraform plan:

    ✓ GCP project 'my-project-123' exists
    ✓ User has roles/editor
    ✓ Required APIs enabled (5/5)
    ✓ Generated 10 Terraform files
    

    Terraform Plan:
    ──────────────────────────────────────────────
    

    + google_cloud_run_v2_service.runtime
    + google_cloud_run_v2_service.cloud_api
    + google_cloud_run_v2_service.studio
    + google_sql_database_instance.main
    + google_sql_database.astromesh
    + google_sql_database.astromesh_cloud
    + google_redis_instance.cache
    + google_secret_manager_secret.jwt_secret
    + google_vpc_access_connector.main
    + google_service_account.orbit
    + google_project_iam_member.orbit (4 bindings)
    

    Plan: 14 to add, 0 to change, 0 to destroy.
    Estimated monthly cost: ~$30 (Starter preset)

  4. Deploy

    Section titled “Deploy”

    Apply the plan to provision your stack:

    Terminal window
    astromeshctl orbit apply

    Confirm when prompted (or use --auto-approve to skip):

    Do you want to apply this plan? [y/N]: y
    

    Applying...
    ✓ google_service_account.orbit                  (3s)
    ✓ google_vpc_access_connector.main              (45s)
    ✓ google_sql_database_instance.main             (8m 12s)
    ✓ google_redis_instance.cache                   (5m 30s)
    ✓ google_secret_manager_secret.jwt_secret       (2s)
    ✓ google_cloud_run_v2_service.runtime           (12s)
    ✓ google_cloud_run_v2_service.cloud_api         (10s)
    ✓ google_cloud_run_v2_service.studio            (8s)
    

    ╭─ Deployment Complete ─────────────────────────────╮
    │                                                    │
    │  Runtime:  https://astromesh-runtime-abc123.run.app│
    │  Cloud API: https://astromesh-api-abc123.run.app   │
    │  Studio:   https://astromesh-studio-abc123.run.app │
    │                                                    │
    │  Connection details saved to .orbit/orbit.env      │
    │                                                    │
    ╰────────────────────────────────────────────────────╯

  5. Verify

    Section titled “Verify”

    Check the status of your deployment:

    Terminal window
    astromeshctl orbit status
    Deployment: my-astromesh (production)
    Provider:   gcp / my-project-123 / us-central1
    State:      gs://my-project-123-astromesh-orbit-state
    Last applied: 2026-03-18T14:32:00Z
    

    RESOURCE                  TYPE                    STATUS    URL
    astromesh-runtime         cloud_run_v2_service    running   https://astromesh-runtime-abc123.run.app
    astromesh-cloud-api       cloud_run_v2_service    running   https://astromesh-api-abc123.run.app
    astromesh-studio          cloud_run_v2_service    running   https://astromesh-studio-abc123.run.app
    main                      sql_database_instance   running   —
    cache                     redis_instance          running   —

    Test the runtime health endpoint:

    Terminal window
    curl https://astromesh-runtime-abc123.run.app/v1/health
    {"status": "healthy", "version": "0.5.0"}

  6. Clean Up (optional)

    Section titled “Clean Up (optional)”

    When you are done, tear down everything:

    Terminal window
    astromeshctl orbit destroy

What’s Next

Section titled “What’s Next”