0d073fa89e
- Add GETTING_STARTED.md with quick start guide and development modes - Add INSTALL.sh automated installation script - Add INSTALLATION_CHECKLIST.md, INSTALLATION_SUCCESS.md, and INSTALLATION_SUMMARY.md - Add QUICK_REFERENCE.md for common commands - Add SETUP_GUIDE.md with detailed setup instructions - Update README.md with improved project overview - Add did-wallet app dependencies and node_modules
323 lines
5.9 KiB
Markdown
323 lines
5.9 KiB
Markdown
# Archipelago Quick Reference
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Install all dependencies
|
|
./INSTALL.sh
|
|
|
|
# Verify installation
|
|
./verify-install.sh
|
|
```
|
|
|
|
## Development
|
|
|
|
### Start Development Servers
|
|
|
|
```bash
|
|
# Quick start (mock backend)
|
|
./scripts/dev.sh
|
|
|
|
# Interactive start
|
|
./scripts/dev-start.sh
|
|
|
|
# Manual start
|
|
# Terminal 1:
|
|
cd core && cargo run --bin archipelago
|
|
|
|
# Terminal 2:
|
|
cd neode-ui && npm run dev
|
|
```
|
|
|
|
### URLs
|
|
|
|
- Frontend: http://localhost:8100
|
|
- Backend API: http://localhost:5959
|
|
- Backend RPC: http://localhost:5959/rpc/v1
|
|
|
|
## Common Commands
|
|
|
|
### Rust Backend
|
|
|
|
```bash
|
|
cd core
|
|
|
|
# Run in development mode
|
|
cargo run --bin archipelago
|
|
|
|
# Run in release mode (faster)
|
|
cargo run --bin archipelago --release
|
|
|
|
# Build only
|
|
cargo build
|
|
|
|
# Run tests
|
|
cargo test
|
|
|
|
# Auto-reload on changes
|
|
cargo install cargo-watch
|
|
cargo watch -x 'run --bin archipelago'
|
|
|
|
# Check for errors without building
|
|
cargo check
|
|
```
|
|
|
|
### Frontend (Vue.js)
|
|
|
|
```bash
|
|
cd neode-ui
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development server
|
|
npm run dev
|
|
|
|
# With mock backend
|
|
npm run dev:mock
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Type checking
|
|
npm run type-check
|
|
|
|
# Preview production build
|
|
npm run preview
|
|
```
|
|
|
|
### Apps (Containerized)
|
|
|
|
```bash
|
|
cd apps
|
|
|
|
# Build all apps
|
|
./build.sh
|
|
|
|
# Build specific app
|
|
./build.sh router
|
|
./build.sh bitcoin-core
|
|
./build.sh did-wallet
|
|
|
|
# Install app dependencies (for custom apps)
|
|
cd apps/router && npm install
|
|
cd apps/did-wallet && npm install
|
|
cd apps/web5-dwn && npm install
|
|
```
|
|
|
|
### Container Management (Podman)
|
|
|
|
```bash
|
|
# Check Podman status
|
|
podman --version
|
|
podman info
|
|
|
|
# Manage Podman machine
|
|
podman machine list
|
|
podman machine start
|
|
podman machine stop
|
|
podman machine ssh
|
|
|
|
# List containers
|
|
podman ps
|
|
podman ps -a
|
|
|
|
# List images
|
|
podman images
|
|
|
|
# Remove all stopped containers
|
|
podman container prune
|
|
|
|
# Remove unused images
|
|
podman image prune
|
|
```
|
|
|
|
### Database (PostgreSQL)
|
|
|
|
```bash
|
|
# Start/stop PostgreSQL service
|
|
brew services start postgresql@15
|
|
brew services stop postgresql@15
|
|
brew services restart postgresql@15
|
|
|
|
# Check service status
|
|
brew services list | grep postgresql
|
|
|
|
# Create database
|
|
createdb archipelago_dev
|
|
|
|
# Drop database
|
|
dropdb archipelago_dev
|
|
|
|
# Connect to database
|
|
psql archipelago_dev
|
|
|
|
# List databases
|
|
psql -l
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Backend Configuration
|
|
|
|
File: `core/.env`
|
|
|
|
```bash
|
|
DATADIR=/tmp/archipelago-dev
|
|
RPC_BIND=127.0.0.1:5959
|
|
LOG_LEVEL=debug
|
|
DATABASE_URL=postgresql://localhost/archipelago_dev
|
|
ARCHIPELAGO_DEV_MODE=true
|
|
```
|
|
|
|
### Frontend Configuration
|
|
|
|
File: `neode-ui/.env`
|
|
|
|
```bash
|
|
VITE_BACKEND_URL=http://localhost:5959
|
|
VITE_API_BASE=/rpc/v1
|
|
VITE_DEV_MODE=true
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Ports Already in Use
|
|
|
|
```bash
|
|
# Find process using port
|
|
lsof -i :5959
|
|
lsof -i :8100
|
|
|
|
# Kill process
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### PostgreSQL Issues
|
|
|
|
```bash
|
|
# Check if running
|
|
pg_isready
|
|
|
|
# View logs
|
|
tail -f /opt/homebrew/var/log/postgresql@15.log
|
|
|
|
# Restart service
|
|
brew services restart postgresql@15
|
|
```
|
|
|
|
### Podman Issues
|
|
|
|
```bash
|
|
# Restart machine
|
|
podman machine stop
|
|
podman machine start
|
|
|
|
# Reset machine (WARNING: destroys all containers/images)
|
|
podman machine rm
|
|
podman machine init
|
|
podman machine start
|
|
```
|
|
|
|
### Rust Compilation Issues
|
|
|
|
```bash
|
|
# Update Rust
|
|
rustup update
|
|
|
|
# Clean and rebuild
|
|
cd core
|
|
cargo clean
|
|
cargo build
|
|
```
|
|
|
|
### Node/NPM Issues
|
|
|
|
```bash
|
|
# Clear cache and reinstall
|
|
rm -rf node_modules package-lock.json
|
|
npm cache clean --force
|
|
npm install
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
archy/
|
|
├── INSTALL.sh # Installation script
|
|
├── verify-install.sh # Verify installation
|
|
├── SETUP_GUIDE.md # Detailed setup guide
|
|
├── README.md # Main documentation
|
|
├── core/ # Rust backend
|
|
│ ├── .env # Backend config (create from .env.example)
|
|
│ ├── archipelago/ # Main binary
|
|
│ ├── container/ # Container management
|
|
│ ├── parmanode/ # Parmanode integration
|
|
│ ├── security/ # Security modules
|
|
│ └── performance/ # Performance optimization
|
|
├── neode-ui/ # Vue.js frontend
|
|
│ ├── .env # Frontend config (create from .env.example)
|
|
│ └── src/ # Source files
|
|
├── apps/ # Containerized applications
|
|
│ ├── build.sh # Build apps
|
|
│ ├── bitcoin-core/ # Bitcoin node
|
|
│ ├── router/ # Custom router app
|
|
│ ├── did-wallet/ # Web5 DID wallet
|
|
│ └── web5-dwn/ # Web5 DWN server
|
|
├── docs/ # Documentation
|
|
├── scripts/ # Development scripts
|
|
└── image-recipe/ # OS image build files
|
|
```
|
|
|
|
## Useful Aliases
|
|
|
|
Add to your `~/.zshrc` or `~/.bashrc`:
|
|
|
|
```bash
|
|
# Archipelago aliases
|
|
alias archy-backend='cd ~/Projects/archy/core && cargo run --bin archipelago'
|
|
alias archy-frontend='cd ~/Projects/archy/neode-ui && npm run dev'
|
|
alias archy-verify='cd ~/Projects/archy && ./verify-install.sh'
|
|
alias archy-apps='cd ~/Projects/archy/apps'
|
|
alias archy-docs='cd ~/Projects/archy/docs'
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Start backend** (Terminal 1)
|
|
```bash
|
|
cd core && cargo run --bin archipelago
|
|
```
|
|
|
|
2. **Start frontend** (Terminal 2)
|
|
```bash
|
|
cd neode-ui && npm run dev
|
|
```
|
|
|
|
3. **Make changes** to code
|
|
|
|
4. **See changes live:**
|
|
- Frontend: Auto-reloads with Vite HMR
|
|
- Backend: Restart cargo or use cargo-watch
|
|
|
|
5. **Build apps** when needed:
|
|
```bash
|
|
cd apps && ./build.sh <app-name>
|
|
```
|
|
|
|
## Resources
|
|
|
|
- [Development Setup Guide](docs/development-setup.md)
|
|
- [Architecture Documentation](docs/architecture.md)
|
|
- [App Manifest Specification](docs/app-manifest-spec.md)
|
|
- [Apps Quick Start](apps/QUICKSTART.md)
|
|
- [Apps Development Guide](apps/DEVELOPMENT.md)
|
|
|
|
## Getting Help
|
|
|
|
1. Check [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed instructions
|
|
2. Run `./verify-install.sh` to diagnose issues
|
|
3. Review error messages carefully
|
|
4. Check service status (PostgreSQL, Podman)
|
|
5. Look in `docs/` for specific topics
|