archy/GETTING_STARTED.md

🚀 Archipelago - Getting Started

Welcome to Archipelago! This guide will get you up and running in minutes.

⚡ Quick Start

Step 1: Install Dependencies

Run the automated installation script:

./INSTALL.sh

This installs everything you need:

• ✅ Rust (latest stable)
• ✅ Node.js 18+
• ✅ Podman (container runtime)
• ✅ PostgreSQL 15
• ✅ All project dependencies

Note: The script requires administrator privileges for Homebrew and system tools.

Step 2: Verify Installation

./verify-install.sh

This checks that all dependencies are properly installed and configured.

Step 3: Configure (Optional)

Copy environment files and adjust if needed:

# Backend configuration
cp core/.env.example core/.env

# Frontend configuration
cp neode-ui/.env.example neode-ui/.env

Step 4: Start Development

Open two terminal windows:

Terminal 1 - Backend:

cd core
cargo run --bin archipelago

Terminal 2 - Frontend:

cd neode-ui
npm run dev

Step 5: Open in Browser

Navigate to: http://localhost:8100

---

📋 What Gets Installed

Tool	Purpose	Version Required
Rust	Backend development	Latest stable (1.93+)
Node.js	Frontend & custom apps	v18 or higher
Podman	Container runtime	Latest
PostgreSQL	Database	v15
Homebrew	Package manager (macOS)	Latest

---

🎯 Alternative: Manual Installation

If you prefer to install manually or the script fails, follow these steps:

1. Install Homebrew (if not installed)

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

2. Install Rust

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

3. Install Node.js, Podman, and PostgreSQL

brew install node podman postgresql@15

4. Initialize Podman

podman machine init
podman machine start

5. Start PostgreSQL

brew services start postgresql@15
createdb archipelago_dev

6. Install Project Dependencies

# Frontend
cd neode-ui
npm install

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

# Backend (this may take a while)
cd ../../core
cargo build

---

🔍 Verify Everything Works

Run the verification script:

./verify-install.sh

You should see all checkmarks (✓). If you see warnings (⚠) or errors (✗), follow the suggested commands to fix them.

---

🏃 Development Modes

Mode 1: Full Stack (Recommended)

Best for full-stack development with real backend API.

Terminal 1:

cd core && cargo run --bin archipelago

Terminal 2:

cd neode-ui && npm run dev

URLs:

• Frontend: http://localhost:8100
• Backend: http://localhost:5959

Mode 2: Mock Backend (Fastest)

Best for frontend-only development without backend setup.

Single Terminal:

cd neode-ui && npm run dev:mock

URL:

• Frontend: http://localhost:8100
• Mock API: http://localhost:3000

Mode 3: Quick Dev Script

Uses convenience scripts for easy startup.

./scripts/dev.sh          # Mock backend mode
# or
./scripts/dev-start.sh    # Interactive mode

---

📁 Project Structure

archy/
├── 📄 INSTALL.sh                # Install all dependencies
├── 📄 verify-install.sh         # Verify installation
├── 📄 SETUP_GUIDE.md            # Detailed setup guide
├── 📄 QUICK_REFERENCE.md        # Command reference
├── 📄 README.md                 # Main documentation
│
├── 🦀 core/                     # Rust backend
│   ├── archipelago/            # Main binary
│   ├── container/              # Container management
│   ├── parmanode/              # Parmanode integration
│   ├── security/               # Security modules
│   └── performance/            # Performance optimization
│
├── 🎨 neode-ui/                 # Vue.js frontend
│   ├── src/                    # Source files
│   ├── public/                 # Static assets
│   └── package.json            # Node dependencies
│
├── 📦 apps/                     # Containerized apps
│   ├── bitcoin-core/           # Bitcoin node
│   ├── lnd/                    # Lightning Network
│   ├── router/                 # Mesh router
│   ├── did-wallet/             # Web5 wallet
│   └── web5-dwn/               # Web5 DWN server
│
├── 📚 docs/                     # Documentation
│   ├── development-setup.md
│   ├── architecture.md
│   └── app-manifest-spec.md
│
└── 🔧 scripts/                  # Development scripts
    ├── dev.sh
    └── dev-start.sh

---

🛠️ Common Commands

Development

# Start backend
cd core && cargo run --bin archipelago

# Start frontend
cd neode-ui && npm run dev

# Start with mock backend
cd neode-ui && npm run dev:mock

# Build for production
cd neode-ui && npm run build
cd core && cargo build --release

Container Apps

# Build all apps
cd apps && ./build.sh

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

Maintenance

# Update Rust
rustup update

# Update Node packages
cd neode-ui && npm update

# Check PostgreSQL status
brew services list | grep postgresql

# Check Podman status
podman machine list

---

🐛 Troubleshooting

Port Already in Use

# Find what's using the port
lsof -i :5959   # Backend
lsof -i :8100   # Frontend

# Kill the process
kill -9 <PID>

Podman Not Running

podman machine start

PostgreSQL Not Running

brew services start postgresql@15

Rust Compilation Errors

# Clean and rebuild
cd core
cargo clean
cargo build

Node Module Issues

cd neode-ui
rm -rf node_modules package-lock.json
npm install

---

📖 Next Steps

Once everything is running:

1. Explore the UI at http://localhost:8100

2. Read the docs:

   • SETUP_GUIDE.md - Detailed setup
   • QUICK_REFERENCE.md - Command cheatsheet
   • docs/architecture.md - System architecture
   • apps/QUICKSTART.md - Build and run apps

3. Build containerized apps:

   cd apps
   ./build.sh
   

4. Install apps via UI at http://localhost:8100

---

💡 Tips

• Use cargo watch for auto-reload:

  cargo install cargo-watch
  cd core && cargo watch -x 'run --bin archipelago'
  

• Frontend has hot module replacement (HMR) - changes reflect instantly

• Keep PostgreSQL and Podman running in the background

• Use the mock backend for quick UI prototyping

---

🆘 Getting Help

1. Run ./verify-install.sh to diagnose issues
2. Check the SETUP_GUIDE.md for detailed instructions
3. Review docs/ for specific topics
4. Make sure all services are running (PostgreSQL, Podman)

---

✅ Success Checklist

• Rust installed (rustc --version)
• Node.js installed (node --version)
• Podman installed and running (podman machine list)
• PostgreSQL running (brew services list)
• Frontend dependencies installed (neode-ui/node_modules exists)
• Backend compiles (cd core && cargo build)
• Can access frontend at http://localhost:8100
• Can access backend at http://localhost:5959

---

Welcome to Archipelago! Happy coding! 🎉