232 lines
4.2 KiB
Markdown
232 lines
4.2 KiB
Markdown
# Development Setup Guide
|
|
|
|
This guide explains how to run Archipelago locally for development.
|
|
|
|
## Prerequisites
|
|
|
|
- **Rust** (latest stable) - [Install Rust](https://rustup.rs/)
|
|
- **Node.js** (v18+) and **npm** - [Install Node.js](https://nodejs.org/)
|
|
- **Podman** (for container features) - [Install Podman](https://podman.io/getting-started/installation)
|
|
- **PostgreSQL** (for backend database) - [Install PostgreSQL](https://www.postgresql.org/download/)
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm install
|
|
npm run dev:real
|
|
```
|
|
|
|
Or just:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
DATADIR=/tmp/archipelago-dev
|
|
RPC_BIND=127.0.0.1:5959
|
|
LOG_LEVEL=debug
|
|
```
|
|
|
|
### Frontend
|
|
|
|
Create `.env` in `neode-ui/` directory:
|
|
|
|
```bash
|
|
VITE_BACKEND_URL=http://localhost:5959
|
|
VITE_API_BASE=/rpc/v1
|
|
```
|
|
|
|
## Database Setup
|
|
|
|
The backend uses PostgreSQL. For development:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm test
|
|
```
|
|
|
|
### Backend Tests
|
|
|
|
```bash
|
|
cd core
|
|
cargo test
|
|
```
|
|
|
|
## Building for Production
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd neode-ui
|
|
npm run build
|
|
```
|
|
|
|
Output: `dist/` directory
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd core
|
|
cargo build --release
|
|
```
|
|
|
|
Output: `target/release/startbox`
|
|
|
|
## Next Steps
|
|
|
|
- Read [Architecture Documentation](./architecture.md)
|
|
- Check [App Manifest Specification](./app-manifest-spec.md)
|
|
- Review [Coding Standards](../CODING_STANDARDS.md)
|