Developer Onboarding

Complete guide for setting up your environment and contributing to LUMINA

Internal Guide Updated Jan 2026

1Introduction

Welcome to the LUMINA project. This document outlines the standard operating procedures for setting up your development environment and contributing to the codebase. We follow a strict Dev → Prod deployment strategy facilitated by Render and GitHub Actions.

2Prerequisites

Ensure the following tools are installed and configured before starting:

  • Git: Version control (ensure access to aenfr org).
  • Python 3.10+: Core language for Orchestrator and setup scripts.
  • Docker Access: Required for Engine updates (if working on lumina-engine).
  • Code Editor: VS Code is recommended for workspace settings.

3Initial Setup

Clone the bootstrap repo and run the setup script:

git clone https://github.com/aenfr/lumina-bootstrap.git
cd lumina-bootstrap
python lumina_setup.py ../lumina-workspace

This automates cloning all repos, installing dependencies, and creating .agent/workflows/ with documentation for coding agents (architecture, git workflow, project overview).

!
Environment Variables (Optional)

Note: This step is only required if you want to run the orchestrator locally (e.g., for debugging new endpoints). For most contributors working on the dashboard or deploying to Render, you can skip this—all environment variables are already configured in Render.

If running locally, create .env in lumina-orchestrator/ with credentials from the technical lead.

4System Architecture

The system consists of three distinct components:

  • Dashboard (Static Site): The frontend interface. Configured via js/config.js to automatically switch API endpoints based on the environment.
  • Orchestrator (FastAPI): The backend API managing user auth, job queues, and GPU provisioning.
  • Engine (Docker/GPU): The generative model runtime deployed on Lambda Labs GPUs.

5Development Workflow

All development work occurs strictly on the dev branch.

Step 1: Local Development

Always pull the latest changes before starting:

git checkout dev
git pull origin dev

Run services locally for rapid testing:

  • Orchestrator: uvicorn main:app --reload (Runs on port 8000)
  • Dashboard: python -m http.server 3000 (Runs on port 3000)

6Deployment (Automated)

We use a Push-to-Deploy workflow. When you are ready to deploy your changes to the shared Dev environment:

1. Commit & Push

git add .
git commit -m "feat: description of changes"
git push origin dev

2. CI/CD Pipeline Triggers

  • Dashboard: Render automatically rebuilds and deploys to dashboard-dev-7klv.onrender.com.
  • Orchestrator: Render automatically rebuilds and deploys to lumina-orchestrator-dev.onrender.com.
  • Engine: GitHub Actions builds a Docker image tagged :dev and pushes to GHCR.

3. Verification

Verify your changes in the cloud Dev environment:

Note: The Dev Dashboard is pre-configured to communicate with the Dev Orchestrator. The Dev Orchestrator is pre-configured to spawn GPU instances using the dev engine image.