mid coding commit
This commit is contained in:
zazawowow
@@ -0,0 +1,319 @@
|
||||
# Building Archipelago OS Images
|
||||
|
||||
This guide explains how to build bootable Alpine Linux OS images for Archipelago Bitcoin Node OS that can be flashed to x86_64 desktop computers (Dell Optiplex, HP ProDesk 400 G4 DM, etc.).
|
||||
|
||||
## Overview
|
||||
|
||||
The build system creates bootable ISO or disk images containing:
|
||||
- Alpine Linux base system
|
||||
- Podman container runtime
|
||||
- Archipelago backend (Rust)
|
||||
- Archipelago frontend (Vue.js)
|
||||
- Systemd services
|
||||
- Network configuration
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### macOS
|
||||
|
||||
- **Docker Desktop**: [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
|
||||
- **Disk Space**: At least 10GB free
|
||||
- **Memory**: 8GB+ recommended
|
||||
|
||||
### Linux (HP ProDesk 400 G4 DM)
|
||||
|
||||
- **Alpine Linux** (preferred) or any Linux with Docker
|
||||
- **Build Tools**: See installation below
|
||||
- **Disk Space**: At least 10GB free
|
||||
|
||||
## Quick Start
|
||||
|
||||
### On macOS
|
||||
|
||||
```bash
|
||||
cd image-recipe
|
||||
./build-macos.sh
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Build Docker container with all tools
|
||||
2. Compile backend and frontend
|
||||
3. Create Alpine image with Archipelago
|
||||
4. Output ISO to `results/` directory
|
||||
|
||||
### On Linux
|
||||
|
||||
```bash
|
||||
cd image-recipe
|
||||
./build-linux.sh
|
||||
```
|
||||
|
||||
For native Alpine Linux:
|
||||
```bash
|
||||
cd image-recipe
|
||||
./build-alpine-native.sh
|
||||
```
|
||||
|
||||
## Build Process
|
||||
|
||||
### Step 1: Build Backend
|
||||
|
||||
The backend is compiled from Rust source:
|
||||
|
||||
```bash
|
||||
./scripts/build-backend.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `build/backend/archipelago` - Compiled binary
|
||||
|
||||
### Step 2: Build Frontend
|
||||
|
||||
The frontend is built from Vue.js source:
|
||||
|
||||
```bash
|
||||
./scripts/build-frontend.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `build/frontend/` - Static files
|
||||
|
||||
### Step 3: Create APK Package
|
||||
|
||||
Backend is packaged as Alpine APK:
|
||||
|
||||
```bash
|
||||
./scripts/create-backend-apk.sh
|
||||
```
|
||||
|
||||
This creates:
|
||||
- `apks/archipelago-backend-*.apk`
|
||||
|
||||
### Step 4: Build OS Image
|
||||
|
||||
The main build script orchestrates everything:
|
||||
|
||||
```bash
|
||||
./build-alpine-iso.sh
|
||||
```
|
||||
|
||||
Or build specific type:
|
||||
|
||||
```bash
|
||||
BUILD_TYPE=iso ./build-alpine-iso.sh
|
||||
BUILD_TYPE=disk ./build-alpine-iso.sh
|
||||
```
|
||||
|
||||
## Build Types
|
||||
|
||||
### ISO Image
|
||||
|
||||
Creates a bootable ISO file suitable for:
|
||||
- Burning to DVD
|
||||
- Writing to USB drive
|
||||
- Booting in virtual machines
|
||||
|
||||
```bash
|
||||
BUILD_TYPE=iso ./build-alpine-iso.sh
|
||||
```
|
||||
|
||||
Output: `results/archipelago-0.1.0-x86_64.iso`
|
||||
|
||||
### Disk Image
|
||||
|
||||
Creates a raw disk image suitable for:
|
||||
- Direct flashing to SSD/HDD
|
||||
- Using with `dd` command
|
||||
- Virtual machine disk
|
||||
|
||||
```bash
|
||||
BUILD_TYPE=disk ./build-alpine-iso.sh
|
||||
```
|
||||
|
||||
Output: `results/archipelago-0.1.0-x86_64.img`
|
||||
|
||||
## Flashing to Device
|
||||
|
||||
### Using ISO (USB Boot)
|
||||
|
||||
1. **Write ISO to USB**:
|
||||
```bash
|
||||
# macOS
|
||||
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/rdiskX bs=1m
|
||||
|
||||
# Linux
|
||||
sudo dd if=results/archipelago-0.1.0-x86_64.iso of=/dev/sdX bs=1M
|
||||
```
|
||||
|
||||
2. **Boot from USB** on target device
|
||||
3. **Install to disk** (if installer included) or run live
|
||||
|
||||
### Using Disk Image (Direct Flash)
|
||||
|
||||
1. **Connect target disk** to build machine
|
||||
2. **Flash image**:
|
||||
```bash
|
||||
# macOS
|
||||
sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/rdiskX bs=1m
|
||||
|
||||
# Linux
|
||||
sudo dd if=results/archipelago-0.1.0-x86_64.img of=/dev/sdX bs=1M
|
||||
```
|
||||
|
||||
3. **Boot from disk** on target device
|
||||
|
||||
⚠️ **Warning**: Double-check the device path! Flashing to wrong device will destroy data.
|
||||
|
||||
## Customization
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Version
|
||||
ARCHIPELAGO_VERSION=0.1.0
|
||||
|
||||
# Alpine version
|
||||
ALPINE_VERSION=3.19
|
||||
|
||||
# Architecture
|
||||
ARCH=x86_64
|
||||
|
||||
# Build type
|
||||
BUILD_TYPE=iso # or "disk"
|
||||
|
||||
# Output directory
|
||||
OUTPUT_DIR=./results
|
||||
```
|
||||
|
||||
### Custom Profile
|
||||
|
||||
Edit `alpine-profile/mkimg.archipelago.sh` to:
|
||||
- Add/remove packages
|
||||
- Change kernel options
|
||||
- Modify boot configuration
|
||||
|
||||
### Overlay Files
|
||||
|
||||
Add files to `alpine-profile/overlay/` to include in image:
|
||||
- Configuration files
|
||||
- Scripts
|
||||
- Service files
|
||||
|
||||
## Build Output
|
||||
|
||||
After successful build, you'll find:
|
||||
|
||||
```
|
||||
results/
|
||||
├── archipelago-0.1.0-x86_64.iso # Bootable ISO
|
||||
└── archipelago-0.1.0-x86_64.img # Disk image (if disk build)
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Docker Issues (macOS)
|
||||
|
||||
**Problem**: Docker daemon not running
|
||||
```bash
|
||||
# Start Docker Desktop application
|
||||
open -a Docker
|
||||
```
|
||||
|
||||
**Problem**: Out of disk space
|
||||
```bash
|
||||
# Clean Docker
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
### Build Failures
|
||||
|
||||
**Problem**: Backend build fails
|
||||
```bash
|
||||
# Check Rust installation
|
||||
rustc --version
|
||||
|
||||
# Install Rust if needed
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
**Problem**: Frontend build fails
|
||||
```bash
|
||||
# Check Node.js
|
||||
node --version # Need 18+
|
||||
|
||||
# Install dependencies
|
||||
cd neode-ui
|
||||
npm install
|
||||
```
|
||||
|
||||
**Problem**: Alpine aports clone fails
|
||||
```bash
|
||||
# Manual clone
|
||||
cd image-recipe
|
||||
git clone https://gitlab.alpinelinux.org/alpine/aports.git
|
||||
```
|
||||
|
||||
### Image Boot Issues
|
||||
|
||||
**Problem**: Image doesn't boot
|
||||
- Verify ISO/image integrity
|
||||
- Check BIOS/UEFI settings
|
||||
- Ensure correct architecture (x86_64)
|
||||
- Try different boot mode (UEFI vs Legacy)
|
||||
|
||||
**Problem**: Services don't start
|
||||
- Check logs: `journalctl -u archipelago`
|
||||
- Verify network: `ip addr`
|
||||
- Check Podman: `podman info`
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Building on Remote Linux Machine
|
||||
|
||||
```bash
|
||||
# On macOS, copy project
|
||||
scp -r Archipelago user@linux-machine:/tmp/
|
||||
|
||||
# SSH to Linux machine
|
||||
ssh user@linux-machine
|
||||
|
||||
# Build
|
||||
cd /tmp/Archipelago/image-recipe
|
||||
./build-linux.sh
|
||||
```
|
||||
|
||||
### Cross-Compilation
|
||||
|
||||
For building on different architecture:
|
||||
|
||||
```bash
|
||||
# Install cross-compilation tools
|
||||
apk add cross-x86_64-linux-musl
|
||||
|
||||
# Build with target
|
||||
cargo build --release --target x86_64-unknown-linux-musl
|
||||
```
|
||||
|
||||
### Custom Kernel
|
||||
|
||||
To use custom kernel options:
|
||||
|
||||
1. Edit `alpine-profile/mkimg.archipelago.sh`
|
||||
2. Modify `kernel_flavors` or `kernel_addons`
|
||||
3. Rebuild image
|
||||
|
||||
## Next Steps
|
||||
|
||||
After building and flashing:
|
||||
|
||||
1. **Boot the device**
|
||||
2. **Access web UI**: http://device-ip:8100
|
||||
3. **Configure network** (if needed)
|
||||
4. **Install apps** via UI
|
||||
5. **Set up Bitcoin node** (if desired)
|
||||
|
||||
## Resources
|
||||
|
||||
- [Alpine Linux mkimage Documentation](https://wiki.alpinelinux.org/wiki/How_to_make_a_custom_ISO_image)
|
||||
- [Archipelago Architecture](./architecture.md)
|
||||
- [Development Setup](./development-setup.md)
|
||||
@@ -0,0 +1,54 @@
|
||||
# Current Development State
|
||||
|
||||
## What We're Actually Using
|
||||
|
||||
### ✅ NEW Archipelago Components (Following Plan)
|
||||
- **Container Orchestration** (`core/container/`) - Our NEW implementation
|
||||
- **Security Modules** (`core/security/`) - Our NEW implementation
|
||||
- **Performance Modules** (`core/performance/`) - Our NEW implementation
|
||||
- **Parmanode Compatibility** (`core/parmanode/`) - Our NEW implementation
|
||||
- **App Manifests** (`apps/*/manifest.yml`) - Our NEW YAML format
|
||||
- **Container RPC Endpoints** (`core/startos/src/container/`) - Our NEW API layer
|
||||
- **Vue.js Container Views** - Our NEW UI components
|
||||
|
||||
### ⚠️ TEMPORARY StartOS Dependencies (To Be Replaced)
|
||||
- **Backend Binary** (`startbox`) - Still using StartOS binary temporarily
|
||||
- **Backend Core** (`core/startos/`) - StartOS fork, being extended with our modules
|
||||
- **Some RPC Infrastructure** - StartOS RPC system, we're adding to it
|
||||
|
||||
## Development Strategy
|
||||
|
||||
### Phase 1: Extension (Current)
|
||||
- ✅ Use our new container orchestration modules
|
||||
- ✅ Add container RPC endpoints to StartOS backend
|
||||
- ✅ Use our new app manifest system
|
||||
- ⚠️ Still running `startbox` binary (StartOS) as base
|
||||
|
||||
### Phase 2: Refactoring (Next)
|
||||
- 🔄 Replace StartOS-specific code with Archipelago-native
|
||||
- 🔄 Create our own backend binary (`archipelago` or `arch`)
|
||||
- 🔄 Remove StartOS dependencies
|
||||
- 🔄 Build on Alpine Linux base
|
||||
|
||||
### Phase 3: Complete Independence
|
||||
- ✅ Pure Archipelago implementation
|
||||
- ✅ No StartOS code remaining
|
||||
- ✅ Alpine Linux + Podman only
|
||||
|
||||
## What We Should Be Doing NOW
|
||||
|
||||
### For Development
|
||||
1. **Use Mock Backend** - For UI development, mock backend is fine
|
||||
2. **Use Our New Modules** - All container code uses `archipelago-container`
|
||||
3. **Use Our App Manifests** - All apps defined in `apps/*/manifest.yml`
|
||||
4. **Mark StartOS Code** - Add `// TODO: Refactor to Archipelago-native` comments
|
||||
|
||||
### For Backend
|
||||
- Currently: Using StartOS backend as base, extending with our modules
|
||||
- Future: Build our own Archipelago backend that uses ONLY our modules
|
||||
|
||||
## Key Point
|
||||
|
||||
**We ARE following the plan** - we built all the NEW Archipelago components. We're just using StartOS backend temporarily as a base while we extend it. The plan was to "integrate with existing Rust backend via enhanced API layer" - which is what we did.
|
||||
|
||||
But you're right - we should be moving toward complete independence. The mock backend is fine for now since we're developing the UI and container management features.
|
||||
@@ -0,0 +1,384 @@
|
||||
# Development Container Environment Guide
|
||||
|
||||
This guide explains how to develop and test containers in the Archipelago development environment.
|
||||
|
||||
## Overview
|
||||
|
||||
The development server environment enables:
|
||||
- Testing prepackaged containers (k484 mortar, atob nostrdevs)
|
||||
- Installing and running containers with port offsetting for dev
|
||||
- Simulating Bitcoin Core installation and availability
|
||||
- Supporting both Podman (preferred) and Docker (fallback)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Dev Server Environment │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Backend │ │ Container │ │ Port │ │
|
||||
│ │ (Rust) │ │ Runtime │ │ Manager │ │
|
||||
│ │ │ │ (Podman/ │ │ (Offset) │ │
|
||||
│ │ │ │ Docker) │ │ │ │
|
||||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||||
│ │ │ │ │
|
||||
│ └─────────────────┼─────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────▼────────┐ │
|
||||
│ │ Dev Container │ │
|
||||
│ │ Orchestrator │ │
|
||||
│ │ - Port offset │ │
|
||||
│ │ - Bitcoin mock │ │
|
||||
│ │ - Volume dev │ │
|
||||
│ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Container Runtime**: Podman (preferred) or Docker
|
||||
- Podman: https://podman.io/getting-started/installation
|
||||
- Docker: https://docs.docker.com/get-docker/
|
||||
|
||||
2. **Rust**: Latest stable version
|
||||
- Install from: https://rustup.rs/
|
||||
|
||||
3. **Node.js**: v18+ and npm
|
||||
- Install from: https://nodejs.org/
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Check Container Runtime
|
||||
|
||||
```bash
|
||||
./scripts/dev-container.sh
|
||||
```
|
||||
|
||||
This script will:
|
||||
- Check for Podman and Docker availability
|
||||
- Show which runtime will be used
|
||||
- Provide helper commands
|
||||
|
||||
### 2. Start Development Server
|
||||
|
||||
```bash
|
||||
./scripts/dev-start.sh
|
||||
# Choose option 5: Full stack with container support
|
||||
```
|
||||
|
||||
Or manually:
|
||||
|
||||
```bash
|
||||
# Terminal 1: Backend
|
||||
cd core
|
||||
ARCHIPELAGO_DEV_MODE=true \
|
||||
ARCHIPELAGO_CONTAINER_RUNTIME=auto \
|
||||
ARCHIPELAGO_PORT_OFFSET=10000 \
|
||||
ARCHIPELAGO_BITCOIN_SIMULATION=mock \
|
||||
cargo run --bin archipelago
|
||||
|
||||
# Terminal 2: Frontend
|
||||
cd neode-ui
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 3. Install a Container
|
||||
|
||||
Via UI:
|
||||
1. Open http://localhost:8100
|
||||
2. Navigate to Marketplace or Apps
|
||||
3. Install a container app
|
||||
|
||||
Via RPC:
|
||||
```bash
|
||||
curl -X POST http://localhost:5959/rpc/v1 \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"method": "container-install",
|
||||
"params": {
|
||||
"manifest_path": "apps/bitcoin-core/manifest.yml"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Port Offset Strategy
|
||||
|
||||
In development mode, ports are offset by 10000 to prevent conflicts with production services:
|
||||
|
||||
| Production Port | Dev Port | Example |
|
||||
|----------------|----------|---------|
|
||||
| 8332 | 18332 | Bitcoin Core RPC |
|
||||
| 8333 | 18333 | Bitcoin Core P2P |
|
||||
| 9735 | 19735 | Lightning Network |
|
||||
| 8080 | 18080 | Web Services |
|
||||
|
||||
This is configurable via `ARCHIPELAGO_PORT_OFFSET` environment variable.
|
||||
|
||||
## Container Runtime
|
||||
|
||||
The system supports three runtime modes:
|
||||
|
||||
1. **Podman** (preferred): Matches production environment
|
||||
2. **Docker**: Easier local development
|
||||
3. **Auto**: Tries Podman first, falls back to Docker
|
||||
|
||||
Set via `ARCHIPELAGO_CONTAINER_RUNTIME` environment variable.
|
||||
|
||||
## Bitcoin Simulation
|
||||
|
||||
Bitcoin Core dependency can be simulated in three ways:
|
||||
|
||||
1. **Mock** (default): Fast, no actual node required
|
||||
- Mocks Bitcoin RPC responses
|
||||
- Satisfies dependencies without installation
|
||||
- Use for UI and integration testing
|
||||
|
||||
2. **Testnet**: Runs real Bitcoin Core on testnet
|
||||
- Slower but more realistic
|
||||
- Requires Bitcoin Core container
|
||||
- Use for testing Bitcoin integration
|
||||
|
||||
3. **Mainnet**: Runs real Bitcoin Core on mainnet
|
||||
- Slowest, most realistic
|
||||
- Requires Bitcoin Core container and full sync
|
||||
- Use for final testing
|
||||
|
||||
4. **None**: No Bitcoin simulation
|
||||
- Apps requiring Bitcoin will fail dependency check
|
||||
- Use when testing non-Bitcoin apps
|
||||
|
||||
Set via `ARCHIPELAGO_BITCOIN_SIMULATION` environment variable.
|
||||
|
||||
## Testing Prepackaged Containers
|
||||
|
||||
### Test a Single Container
|
||||
|
||||
```bash
|
||||
./scripts/test-container.sh <app-id> <package-dir>
|
||||
```
|
||||
|
||||
Example:
|
||||
```bash
|
||||
./scripts/test-container.sh k484 ~/k484-package
|
||||
```
|
||||
|
||||
This script will:
|
||||
1. Build the container image
|
||||
2. Create a test manifest
|
||||
3. Install via RPC
|
||||
4. Start the container
|
||||
5. Show status and logs
|
||||
6. Provide cleanup commands
|
||||
|
||||
### Test Multiple Containers
|
||||
|
||||
```bash
|
||||
./scripts/prepackage-test.sh
|
||||
```
|
||||
|
||||
This script tests k484 and atob containers if their package directories are found.
|
||||
|
||||
## Development Data Directories
|
||||
|
||||
Container data is stored in isolated directories:
|
||||
|
||||
- **Location**: `/tmp/archipelago-dev/{app-id}/`
|
||||
- **Purpose**: Separate from production data, easy cleanup
|
||||
- **Persistence**: Data is preserved between container restarts (optional)
|
||||
|
||||
Configure via `ARCHIPELAGO_DEV_DATA_DIR` environment variable.
|
||||
|
||||
## RPC Endpoints
|
||||
|
||||
All container operations are available via RPC:
|
||||
|
||||
### Install Container
|
||||
```json
|
||||
{
|
||||
"method": "container-install",
|
||||
"params": {
|
||||
"manifest_path": "apps/bitcoin-core/manifest.yml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Start Container
|
||||
```json
|
||||
{
|
||||
"method": "container-start",
|
||||
"params": {
|
||||
"app_id": "bitcoin-core"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Stop Container
|
||||
```json
|
||||
{
|
||||
"method": "container-stop",
|
||||
"params": {
|
||||
"app_id": "bitcoin-core"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List Containers
|
||||
```json
|
||||
{
|
||||
"method": "container-list",
|
||||
"params": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Container Status
|
||||
```json
|
||||
{
|
||||
"method": "container-status",
|
||||
"params": {
|
||||
"app_id": "bitcoin-core"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Container Logs
|
||||
```json
|
||||
{
|
||||
"method": "container-logs",
|
||||
"params": {
|
||||
"app_id": "bitcoin-core",
|
||||
"lines": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Remove Container
|
||||
```json
|
||||
{
|
||||
"method": "container-remove",
|
||||
"params": {
|
||||
"app_id": "bitcoin-core",
|
||||
"preserve_data": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Health Status
|
||||
```json
|
||||
{
|
||||
"method": "container-health",
|
||||
"params": {}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
```bash
|
||||
# Enable dev mode
|
||||
ARCHIPELAGO_DEV_MODE=true
|
||||
|
||||
# Container runtime (podman|docker|auto)
|
||||
ARCHIPELAGO_CONTAINER_RUNTIME=auto
|
||||
|
||||
# Port offset (default: 10000)
|
||||
ARCHIPELAGO_PORT_OFFSET=10000
|
||||
|
||||
# Bitcoin simulation (mock|testnet|mainnet|none)
|
||||
ARCHIPELAGO_BITCOIN_SIMULATION=mock
|
||||
|
||||
# Dev data directory (default: /tmp/archipelago-dev)
|
||||
ARCHIPELAGO_DEV_DATA_DIR=/tmp/archipelago-dev
|
||||
|
||||
# Backend bind address (default: 127.0.0.1:5959)
|
||||
ARCHIPELAGO_BIND=127.0.0.1:5959
|
||||
|
||||
# Log level (default: info)
|
||||
ARCHIPELAGO_LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
## Helper Commands
|
||||
|
||||
### List All Containers
|
||||
```bash
|
||||
podman ps -a
|
||||
# or
|
||||
docker ps -a
|
||||
```
|
||||
|
||||
### View Container Logs
|
||||
```bash
|
||||
podman logs <container-name>
|
||||
# or
|
||||
docker logs <container-name>
|
||||
```
|
||||
|
||||
### Stop All Archipelago Containers
|
||||
```bash
|
||||
podman ps -a --filter 'name=archipelago-' --format '{{.Names}}' | xargs -r podman stop
|
||||
# or
|
||||
docker ps -a --filter 'name=archipelago-' --format '{{.Names}}' | xargs -r docker stop
|
||||
```
|
||||
|
||||
### Remove All Archipelago Containers
|
||||
```bash
|
||||
podman ps -a --filter 'name=archipelago-' --format '{{.Names}}' | xargs -r podman rm -f
|
||||
# or
|
||||
docker ps -a --filter 'name=archipelago-' --format '{{.Names}}' | xargs -r docker rm -f
|
||||
```
|
||||
|
||||
### Clean Up Dev Data
|
||||
```bash
|
||||
rm -rf /tmp/archipelago-dev
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container Runtime Not Available
|
||||
|
||||
**Problem**: `No container runtime available`
|
||||
|
||||
**Solution**:
|
||||
1. Install Podman or Docker
|
||||
2. Start the daemon:
|
||||
- Podman (macOS): `podman machine start`
|
||||
- Docker: Start Docker Desktop or `sudo systemctl start docker`
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
**Problem**: Port conflict when starting container
|
||||
|
||||
**Solution**:
|
||||
1. Change port offset: `ARCHIPELAGO_PORT_OFFSET=20000`
|
||||
2. Or stop conflicting service
|
||||
|
||||
### Bitcoin Dependency Not Satisfied
|
||||
|
||||
**Problem**: App requires Bitcoin Core but simulation is disabled
|
||||
|
||||
**Solution**:
|
||||
1. Enable Bitcoin simulation: `ARCHIPELAGO_BITCOIN_SIMULATION=mock`
|
||||
2. Or install Bitcoin Core container first
|
||||
|
||||
### Container Fails to Start
|
||||
|
||||
**Problem**: Container exits immediately
|
||||
|
||||
**Solution**:
|
||||
1. Check logs: `container-logs` RPC call
|
||||
2. Verify image exists: `podman images` or `docker images`
|
||||
3. Check manifest configuration
|
||||
4. Verify port mappings don't conflict
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Mock Bitcoin by Default**: Fast iteration, no sync required
|
||||
2. **Test with Real Bitcoin When Needed**: Use testnet for integration testing
|
||||
3. **Clean Up Regularly**: Remove unused containers and data
|
||||
4. **Check Logs First**: Container logs provide detailed error information
|
||||
5. **Use Port Offset**: Prevents conflicts with production services
|
||||
6. **Isolate Dev Data**: Keep dev and production data separate
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read [App Manifest Specification](./app-manifest-spec.md)
|
||||
- Review [Architecture Documentation](./architecture.md)
|
||||
- Check [Development Setup Guide](./development-setup.md)
|
||||
@@ -0,0 +1,231 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user