Galileo On-Prem Luna Studio Setup

Prerequisites

• Obtain the CSE-approved luna-studio package, pinned images, questionnaire values, and parent Galileo stack release contract.
• Provision an empty dedicated PostgreSQL database and dedicated object-storage bucket/container. Luna Studio does not bootstrap its database.
• Create the four required Kubernetes Secrets out of band before preflight.
• Select kubernetes or vertex_ai training and document any remote cluster.

Workflow Overview

+-- Intake + topology --+ -> +-- Immutable bundle --+ -> +-- Secret/storage/GPU + render preflight --+
                                                               -> +-- Joint-session handoff --+

When to Activate

• Prepare or review a Galileo/CSE handoff for a standalone Luna Studio install or upgrade.
• Configure GCS, S3, Azure Blob, or MinIO-compatible storage authentication.
• Configure in-cluster GPU Jobs, Vertex AI, or a remote training cluster.
• Produce an overlay when the exact umbrella package proves it owns Luna.
• Diagnose database migration, NextAuth/CORS, route, GPU, or storage failures.

Required Intake

Ask for the Galileo instance console URL and record the exact value, for example https://console.demo-v2.galileocloud.io/. Pass it with --galileo-console-url; do not infer a SaaS hostname for on-prem.

Collect the namespace and release, unique ownership mode, exact chart or umbrella evidence hashes, parent release contract, approved non-secret values, the four Secret name/key contracts, asyncpg database readiness, storage provider/auth/bucket, public hostname, DNS/TLS/CORS/NextAuth alignment, backend and UI images, training platform/images, GPU scheduling, remote-cluster token reference, NetworkPolicy/HPA/PDB choices, and approvals. Never record values.

Ownership and Safety Rules

1. Default to the standalone luna-studio release. Use umbrella-overlay only when the exact pinned umbrella proves ownership; reject dual ownership.
2. Require the four mandatory Secret references: JWT, admin, asyncpg database, and NextAuth. Galileo API integration and cloud/remote credentials are optional only when their features are disabled.
3. Bind frontend_url, CORS origins, UI public URL, DNS, route host, and TLS SAN to the same HTTPS origin.
4. Treat startup alembic upgrade head as a database migration. Upgrades and rollback require backup, release-note, and compatibility evidence.
5. Keep backend/UI on standard nodes. Request nvidia.com/gpu only for Kubernetes training Jobs, with matching node selector and tolerations.
6. Do not claim live GPU validation from a CPU-only environment.
7. Never run a generic helm upgrade --install, automatic rollback, or data purge. Preserve failed state for diagnosis.

Read reference.md, training-and-storage.md, lifecycle-contract.md, and source-ledger.md for production review.

Commands

bash skills/galileo-on-prem-luna-studio-setup/scripts/setup.sh --help

bash skills/galileo-on-prem-luna-studio-setup/scripts/setup.sh \
  --render --spec ./luna-studio.local.yaml \
  --galileo-console-url "https://console.demo-v2.galileocloud.io/" \
  --output-dir ./galileo-on-prem-rendered/luna-studio

bash skills/galileo-on-prem-luna-studio-setup/scripts/validate.sh \
  --output-dir ./galileo-on-prem-rendered/luna-studio

Use the distinct --preflight, --status, --plan-rollback, and --plan-uninstall modes with the evidence gates printed by --help. Every non-uninstall preflight requires new private --image-evidence-file and --endpoint-evidence-file outputs. They bind backend, UI, training, init, hook, Job, and test image digests plus exact chart, inputs, parent target, Helm render, and a credential-free host[:port] inventory derived in memory from non-secret and Secret-backed settings. All historical --apply-* modes are permanent fail-closed sentinels and touch neither the bundle nor Kubernetes. Use the immutable lifecycle.json packet and fresh preflight/image/endpoint evidence in a Galileo/CSE joint session. Umbrella mode always stops at a parent-stack overlay handoff.

Completion Gate

Completion requires unique ownership, four exact Secret/key contracts, an asyncpg connection and successful migrations, storage write/read/delete evidence, healthy backend /health and UI /api/health, working login, route/DNS/TLS/CORS alignment, training image resolution, and either a successful training run or an explicit unvalidated capability record. GPU and remote training remain open until tested on their real targets.

Troubleshooting

Symptom	Likely cause	Resolution
Chart render fails	One of four Secret names is absent	Create it out of band and reference its exact name
Database startup fails	Wrong driver or migration grants	Use postgresql+asyncpg:// and grant schema DDL
Sign-in loops	NextAuth/public URL mismatch	Align route, DNS, SAN, frontend, CORS, and UI URL
Training Job is pending	GPU selector, taint, resource, or plugin mismatch	Verify all scheduling evidence on the training target
Vertex pipeline is missing	Image, location, IAM, or outbound path is wrong	Validate pinned images, pipeline root, IAM, and egress
Direct mutation rejected	Exact package selected umbrella ownership	Submit the overlay through the parent stack lifecycle