Development Setup

This guide provides a condensed overview of the tools and configurations required to contribute to our projects. We prioritize speed, type safety, and modern workflows.

1. Core Runtime & Package Managers

We use uv for Python and Bun for JavaScript/TypeScript to ensure the fastest possible dependency resolution and execution.

Tool	Purpose	Installation
uv	Python package & project management	Installation Guide
Bun	JS/TS runtime & package management	Installation Guide

• Python Version: We target Python 3.13.
• Node.js Version: Managed via Bun.

2. Containerization

All applications must be runnable via Docker. For security, we strictly use Rootless Docker.

• Docker Rootless: Mandatory for local development and production. Follow the official installation steps.
• NVIDIA Container Toolkit: Required if you are working with AI models or GPU-accelerated services.
• Docker Compose: Used for orchestrating multi-container environments (e.g., Frontend + Backend + Database).

Standards

Review our Internal Docker Standards for Dockerfile patterns and orchestration strategies.

3. IDE & Tooling

We recommend VS Code with the following tools for a consistent experience:

• Ruff: For Python linting and formatting (extremely fast).
• Biome: For JavaScript/TypeScript linting and formatting.
• Tailwind CSS IntelliSense: Essential for our UI development.

Coding Standards

Ensure you follow our language-specific guidelines:

• Python Coding Standards
• Nuxt.js + TypeScript Coding Standards

4. Git & Workflow

• Git Workflow: We follow GitHub Flow.
• Security: Always use SHA pinning for GitHub Actions. See Security Standards.
• Dependency Cooldowns: We enforce a 7-day cooldown for new package versions to prevent supply chain attacks. This is pre-configured in pyproject.toml (uv) and bunfig.toml (Bun).

5. Local Project Initialization

Once your environment is set up, you can typically start a project with:

# For Python projects
uv sync
uv run main.py

# For Nuxt projects
bun install
bun run dev

Check the README.md of the specific repository for project-specific instructions and required .env variables.

6. Environment Variables & Secrets

We use Varlock for AI-safe .env file management with schema validation, type-safety, and secret injection from password managers.

• Varlock Setup Guide - Detailed setup for Nuxt and Python projects