Onboarding Setup

Onboarding & Local Development Environment Setup

1. Local Prerequisites & Host Machine Provisioning

Before executing the automated setup scripts, ensure your local development machine satisfies the following hardware and base operating system software dependencies:

  • Operating System: Ubuntu 24.04 LTS, macOS Sonoma, or Windows 11 with WSL2 (Ubuntu 22.04+ base image distribution).
  • Hardware Profile: Minimum 4 physical cores (CPU), 8GB allocated RAM capacity, and at least 25GB free SSD storage allocation.
  • Core Runtimes: Docker Engine v25+ with Compose V2 capability installed on the host.

2. Fast Environment Toolchain Bootstrap

We bypass traditional slow installations (pip, npm) in favor of Rust and Zig-backed runtimes (uv, bun) to guarantee consistent environment generation, even during local internet connectivity drops.

# 1. Install Astral uv (Rust-based hyper-fast Python package toolchain manager)
curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh

# 2. Install Bun (High-performance Javascript runtime and workspace manager)
curl -fsSL [https://bun.sh/install](https://bun.sh/install) | bash

# 3. Source environment paths to update terminal bindings
source ~/.bashrc || source ~/.zshrc

3. Monorepo Repository Architecture & Cloning

Clone the project from our local network mirror repository, initialize the codebase submodules, and navigate into the root project directory structure.

# Clone the repository structure from the local server mirror


# Verify project layout tree structure
# .
# ├── backend/      <- Django application module core (uv controlled)
# ├── frontend/     <- Nuxt 3 Client monorepo layout (Bun controlled)
# └── docker/       <- Local infrastructure compose configurations

4. Backend Provisioning & Database Migration Pipeline

Our Python environment lifecycle relies entirely on uv. Execute the toolchain creation and run structural database setups inside the core backend application container space.

cd backend

# 1. Lock and download specific Python runtime environment
uv python install 3.12

# 2. Virtual environment generation and dependency extraction
uv venv .venv
source .venv/bin/activate

# 3. Sync project dependencies using uv (sub-second resolution execution)
uv sync

# 4. Generate local environmental variables config file
cp .env.example .env

# 5. Populate encryption keys and local PostgreSQL connectivity strings
# Master field encryption key must be a valid 64-character hex string
sed -i 's/FIELD_ENCRYPTION_MASTER_KEY=/FIELD_ENCRYPTION_MASTER_KEY=e3b0c44298fc1c149afbf4

4.1 Local Infrastructure Dependency Lifecycle

Boot up the isolated local supporting service infrastructure layers (PostgreSQL 16, Redis) using the provided lightweight Docker Compose testing manifest profiles:

cd ../docker
docker compose -f docker-compose.dev.yml up -d

# Execute core structural migrations to build local schemas
cd ../backend
uv run python manage.py migrate

# Seed base ICD-11 directory structures and KEML pharmacy inventories
uv run python manage.py loaddata reference_icd11_directory.json
uv run python manage.py seed_local_keml_inventory

5. Frontend Client Provisioning

Switch over to the interface development sandbox, pull standard packages using Bun workspaces, and bind configuration values to point directly at your local backend Django API node.

cd ../frontend

# 1. Synchronize Nuxt 3 monorepo bundle packages via Bun
bun install

# 2. Initialize environment configuration mappings
cp .env.example .env

# Verify that backend proxy target matches your local loopback address
# NUXT_PUBLIC_API_BASE_URL=http://localhost:8000/api/v1

6. Local Parallel Execution Blueprint

Rendering Chart

Open three concurrent terminal windows or multiplexers (tmux) to launch the development environment stacks side by side:

# Terminal 1: Run the Django Ninja Core REST Engine
cd backend && source .venv/bin/activate
uv run python manage.py runserver 0.0.0.0:8000

# Terminal 2: Run the Huey Background Event Task Worker
cd backend && source .venv/bin/activate
uv run python manage.py run_huey

# Terminal 3: Run the Nuxt 3 Web Client Interface Server
cd frontend
bun run dev --host 0.0.0.0 --port 3000

Verify your local environment setup status by visiting http://localhost:3000 to access the main interface landing page, or navigating to http://localhost:8000/api/v1/docs to inspect the live Swagger/OpenAPI documentation schema catalog.

Document Verification Block

Author: Ian Wataka - Backend DeveloperTarget Scope: Local Dev Engineering Machine Provisioning

Stack Selection
Engineering Craft