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:

./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

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

For Apple Silicon Macs, add to your shell profile:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

2. Install Rust

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

Verify installation:

rustc --version
cargo --version

3. Install Node.js

brew install node

Verify installation:

node --version  # Should be v18 or higher
npm --version

4. Install Podman

brew install podman

Initialize Podman machine:

podman machine init
podman machine start

Verify installation:

podman --version
podman info

5. Install PostgreSQL

brew install postgresql@15
brew services start postgresql@15

Create development database:

createdb archipelago_dev

6. Install Project Dependencies

Frontend Dependencies

cd neode-ui
npm install

Custom App Dependencies

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

cd core
cargo build

Environment Configuration

Backend Configuration

Create core/.env:

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:

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

Running the Project

Option 1: Quick Start Scripts

Use the convenience scripts:

# 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

cd core
cargo run --bin archipelago

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

Terminal 2: Frontend

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:

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:

# 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:

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

Common Issues

Podman Machine Not Running

podman machine start

PostgreSQL Not Running

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):

RPC_BIND=127.0.0.1:5958

Frontend (in neode-ui/vite.config.ts):

server: { port: 8101 }

Rust Compilation Issues

Make sure you have the latest stable Rust:

rustup update

Node Module Issues

Clear node modules and reinstall:

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:

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 for detailed development info
• Check docs/architecture.md for system architecture
• See apps/QUICKSTART.md for building and running apps
• Review docs/app-manifest-spec.md for creating apps

Resources

• Rust Documentation
• Vue.js 3 Documentation
• Podman Documentation
• PostgreSQL Documentation

Getting Help

If you encounter issues:

1. Check the 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