archy/SETUP_GUIDE.md

# Archipelago Setup Guide

This guide will walk you through setting up your development environment for Archipelago.

## Prerequisites

- macOS (Darwin)
- Terminal access
- Administrator privileges (for some installations)
- Internet connection

## Quick Installation

Run the automated installation script:

```bash
./INSTALL.sh
```

This script will install and configure:
- ✓ Homebrew (macOS package manager)
- ✓ Rust (latest stable)
- ✓ Node.js 18+
- ✓ Podman (container runtime)
- ✓ PostgreSQL 15
- ✓ All project dependencies

## Manual Installation

If you prefer to install components individually:

### 1. Install Homebrew

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

For Apple Silicon Macs, add to your shell profile:
```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

### 2. Install Rust

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

Verify installation:
```bash
rustc --version
cargo --version
```

### 3. Install Node.js

```bash
brew install node
```

Verify installation:
```bash
node --version  # Should be v18 or higher
npm --version
```

### 4. Install Podman

```bash
brew install podman
```

Initialize Podman machine:
```bash
podman machine init
podman machine start
```

Verify installation:
```bash
podman --version
podman info
```

### 5. Install PostgreSQL

```bash
brew install postgresql@15
brew services start postgresql@15
```

Create development database:
```bash
createdb archipelago_dev
```

### 6. Install Project Dependencies

#### Frontend Dependencies

```bash
cd neode-ui
npm install
```

#### Custom App Dependencies

```bash
cd apps/did-wallet && npm install && cd ../..
cd apps/endurain && npm install && cd ../..
cd apps/morphos-server && npm install && cd ../..
cd apps/router && npm install && cd ../..
cd apps/web5-dwn && npm install && cd ../..
```

#### Build Rust Backend

```bash
cd core
cargo build
```

## Environment Configuration

### Backend Configuration

Create `core/.env`:

```bash
DATADIR=/tmp/archipelago-dev
RPC_BIND=127.0.0.1:5959
LOG_LEVEL=debug
DATABASE_URL=postgresql://localhost/archipelago_dev
```

### Frontend Configuration

Create `neode-ui/.env`:

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

## Running the Project

### Option 1: Quick Start Scripts

Use the convenience scripts:

```bash
# Full stack with interactive prompts
./scripts/dev-start.sh

# Or use the quick dev script (mock backend)
./scripts/dev.sh
```

### Option 2: Manual Start

#### Terminal 1: Backend

```bash
cd core
cargo run --bin archipelago
```

Backend will be available at: http://localhost:5959

#### Terminal 2: Frontend

```bash
cd neode-ui
npm run dev
```

Frontend will be available at: http://localhost:8100

### Option 3: Mock Backend (UI Development Only)

For frontend-only development:

```bash
cd neode-ui
npm run dev:mock
```

This starts a mock backend server and Vite dev server together.

## Verifying Installation

Run these commands to verify everything is installed correctly:

```bash
# Check Rust
rustc --version
cargo --version

# Check Node.js
node --version
npm --version

# Check Podman
podman --version
podman machine list

# Check PostgreSQL
psql --version
brew services list | grep postgresql

# Check project dependencies
cd neode-ui && npm list --depth=0
cd ../core && cargo tree --depth=0
```

## Building Apps

To build the containerized apps:

```bash
cd apps
./build.sh                  # Build all apps
./build.sh router          # Build specific app
```

## Common Issues

### Podman Machine Not Running

```bash
podman machine start
```

### PostgreSQL Not Running

```bash
brew services start postgresql@15
```

### Port Already in Use

If ports 5959 or 8100 are in use, you can change them:

Backend (in `core/.env`):
```bash
RPC_BIND=127.0.0.1:5958
```

Frontend (in `neode-ui/vite.config.ts`):
```typescript
server: { port: 8101 }
```

### Rust Compilation Issues

Make sure you have the latest stable Rust:
```bash
rustup update
```

### Node Module Issues

Clear node modules and reinstall:
```bash
rm -rf node_modules package-lock.json
npm install
```

## Development Workflow

1. **Make code changes** in `core/` or `neode-ui/`
2. **Backend**: Cargo will auto-rebuild on `cargo run`
3. **Frontend**: Vite provides hot module replacement (HMR)
4. **Test changes** in browser at http://localhost:8100

For backend auto-reload, install cargo-watch:
```bash
cargo install cargo-watch
cd core
cargo watch -x 'run --bin archipelago'
```

## Project Structure

```
archy/
├── core/              # Rust backend
│   ├── archipelago/   # Main binary
│   ├── container/     # Container management
│   ├── parmanode/     # Parmanode integration
│   ├── security/      # Security modules
│   └── performance/   # Performance optimization
├── neode-ui/          # Vue.js frontend
├── apps/              # Containerized applications
├── docs/              # Documentation
└── scripts/           # Development scripts
```

## Next Steps

- Read [docs/development-setup.md](docs/development-setup.md) for detailed development info
- Check [docs/architecture.md](docs/architecture.md) for system architecture
- See [apps/QUICKSTART.md](apps/QUICKSTART.md) for building and running apps
- Review [docs/app-manifest-spec.md](docs/app-manifest-spec.md) for creating apps

## Resources

- [Rust Documentation](https://doc.rust-lang.org/)
- [Vue.js 3 Documentation](https://vuejs.org/)
- [Podman Documentation](https://docs.podman.io/)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)

## Getting Help

If you encounter issues:

1. Check the [docs/](docs/) directory for detailed documentation
2. Review error messages carefully
3. Check that all services are running (PostgreSQL, Podman)
4. Verify all dependencies are installed correctly

## License

MIT