Skip to content
Orbit

Development Guide

Development Guide

This guide will help you set up Orbit for development and explain how to contribute to the project.

Prerequisites

Before you begin development, ensure you have these tools installed:

  • Go 1.21 or later
  • Node.js 18 or later
  • pnpm 8 or later
  • Python 3.10 or later
  • Ansible
  • Terraform

Development Environment Setup

First, clone the repository:

Terminal window
git clone https://github.com/orbitscanner/orbit
cd orbit

Backend Setup

The backend consists of a Go API server and Python automation scripts:

Terminal window
# Navigate to backend directory
cd backend


# Install Go dependencies
go mod download


# Set up Python environment
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
pip install -r requirements.txt


# Run the backend in development mode
go run main.go serve

The backend API will be available at http://localhost:8090

Frontend Setup

The frontend is built with SvelteKit and needs to be run separately during development:

Terminal window
# Navigate to frontend directory
cd frontend


# Install dependencies
pnpm install


# Start development server
pnpm dev

The frontend development server will be available at http://localhost:5173

Environment Configuration

Frontend Environment Variables

Create a .env file in the frontend directory:

PUBLIC_POCKETBASE_URL=http://localhost:8090
ORBIT_API_KEY=12345678901234567890123456789012

Backend Environment Variables

The backend uses the following environment variables:

ORBIT_API_KEY=12345678901234567890123456789012
ORBIT_LOG_LEVEL=debug  # Optional, defaults to info

Development Workflow

Hot Reloading

The development environment supports various levels of hot reloading:

  • Frontend: Changes automatically reload in the browser
  • Backend Go: Requires manual restart
  • Backend Python: Files automatically reload

Code Structure

orbit/
├── frontend/           # SvelteKit frontend application
│   ├── src/           # Frontend source code
│   └── static/        # Static assets
├── backend/           # Go backend application
│   ├── api/          # API endpoints
│   ├── core/         # Core business logic
│   └── scripts/      # Python automation scripts
└── docs/             # Documentation

Building for Production

When you need to build for production:

Terminal window
# Build frontend
cd frontend
pnpm build


# Build backend
cd ../backend
go build

Testing

Running Tests

Terminal window
# Frontend tests
cd frontend
pnpm test
pnpm test:e2e  # Run end-to-end tests


# Backend tests
cd backend
go test ./...

Writing Tests

  • Frontend tests use Vitest and Playwright
  • Backend tests use Go’s testing package
  • Include tests with all new features
  • Ensure existing tests pass before submitting PRs

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Write or update tests
  5. Submit a pull request

Pull Request Guidelines

  • Keep changes focused and atomic
  • Follow existing code style
  • Include relevant tests
  • Update documentation
  • Provide clear PR description

Troubleshooting

Common development issues and solutions:

Frontend Issues

  • Clear node_modules and reinstall if dependencies act up
  • Check browser console for errors
  • Verify environment variables are set correctly

Backend Issues

  • Ensure Python virtual environment is activated
  • Check Go version compatibility
  • Verify all dependencies are installed

Getting Help