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 mise to pin and activate the exact runtime versions in every project, uv for Python package management, and Bun for JavaScript/TypeScript. Install mise once; entering a project directory activates the pinned bun, node, python, and uv automatically (run mise trust the first time). See the mise tooling standard for the canonical versions and task names.

Tool	Purpose	Installation
mise	Runtime version manager + task runner (every project's entry point)	Getting Started
uv	Python package & project management	Installation Guide
Bun	JS/TS runtime & package management	Installation Guide

• Tool Versions: Pinned per project in mise.toml — no global installs needed. See the mise tooling standard for details.
• Tasks: Every project is driven through mise run <task> (install, dev, check, test, …) — see the standard task names.

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, every project is driven through mise. Getting started is always the same three steps:

# 1. Approve the project's mise.toml (once per project)
mise trust

# 2. Provision the pinned toolchain and install dependencies
#    (also installs system packages declared in [bootstrap.packages])
mise bootstrap packages apply
mise install

# 3. Run the app
mise run dev

The postinstall hook usually runs the install task automatically after mise install; otherwise start with mise run install.

Common tasks in any project:

mise run check        # lint, format, type-check
mise run test:unit    # unit tests
mise tasks            # list all tasks available in this project

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