archy/docs/development-setup.md

Development Setup Guide

This guide explains how to run Archipelago locally for development.

Prerequisites

• Rust (latest stable) - Install Rust
• Node.js (v18+) and npm - Install Node.js
• Podman (for container features) - Install Podman
• PostgreSQL (for backend database) - Install PostgreSQL

Project Structure

The project has two main components:

1. Backend (core/startos/) - Rust backend with RPC API
2. Frontend (neode-ui/) - Vue.js 3 frontend

Quick Start

Option 1: Mock Backend (Fastest for UI Development)

For frontend-only development, use the mock backend:

cd neode-ui
npm install
npm run dev:mock

This starts:

• Mock backend server on port 3000
• Vite dev server on port 8100
• Open http://localhost:8100

Option 2: Full Stack Development

For full-stack development with the real backend:

Terminal 1: Backend

cd core
cargo run --bin startbox --features cli,daemon

The backend will:

• Start RPC server on port 5959
• Initialize database if needed
• Serve API endpoints

Terminal 2: Frontend

cd neode-ui
npm install
npm run dev:real

Or just:

npm run dev

The frontend will:

• Start Vite dev server on port 8100
• Proxy API requests to backend on port 5959
• Open http://localhost:8100

Development Scripts

Frontend Scripts (neode-ui/package.json)

• npm run dev - Start Vite dev server
• npm run dev:mock - Start with mock backend
• npm run dev:real - Start with real backend (backend must be running separately)
• npm run build - Build for production
• npm run type-check - TypeScript type checking

Backend Scripts

• cargo run --bin startbox - Run backend in dev mode
• cargo run --bin startbox --release - Run backend in release mode
• cargo test - Run tests
• cargo build - Build backend

Environment Variables

Backend

Create .env in core/ directory:

DATADIR=/tmp/archipelago-dev
RPC_BIND=127.0.0.1:5959
LOG_LEVEL=debug

Frontend

Create .env in neode-ui/ directory:

VITE_BACKEND_URL=http://localhost:5959
VITE_API_BASE=/rpc/v1

Database Setup

The backend uses PostgreSQL. For development:

# Create database
createdb archipelago_dev

# Or use Docker
docker run -d \
  --name archipelago-postgres \
  -e POSTGRES_PASSWORD=dev \
  -e POSTGRES_DB=archipelago_dev \
  -p 5432:5432 \
  postgres:15

Container Development

To test container features locally, you need Podman:

# Install Podman (macOS)
brew install podman

# Initialize Podman machine
podman machine init
podman machine start

# Verify
podman --version

Hot Reload

• Frontend: Vite provides instant hot module replacement (HMR)
• Backend: Use cargo watch for auto-reload:

cargo install cargo-watch
cargo watch -x 'run --bin startbox'

Debugging

Frontend

• Use browser DevTools
• Vue DevTools extension recommended
• Console logs available

Backend

• Use RUST_LOG=debug environment variable
• Add println! or use tracing macros
• Use a debugger like lldb or gdb

Common Issues

Port Already in Use

If port 5959 or 8100 is already in use:

# Backend - change port in .env
RPC_BIND=127.0.0.1:5958

# Frontend - change in vite.config.ts
server: { port: 8101 }

Database Connection Errors

• Ensure PostgreSQL is running
• Check connection string in backend config
• Verify database exists

Container Features Not Working

• Ensure Podman is installed and running
• Check Podman machine is started (macOS)
• Verify rootless Podman is configured

Testing

Frontend Tests

cd neode-ui
npm test

Backend Tests

cd core
cargo test

Building for Production

Frontend

cd neode-ui
npm run build

Output: dist/ directory

Backend

cd core
cargo build --release

Output: target/release/startbox

Next Steps

• Read Architecture Documentation
• Check App Manifest Specification
• Review Coding Standards