6035c93289
- Updated BUILD-GUIDE.md to clarify instructions for building the Archipelago Auto-Installer ISO, emphasizing the recommended method of building directly on the target server. - Added auto-installation of missing dependencies (xorriso, podman) when running the build script with sudo. - Enhanced the build-auto-installer-iso.sh script to capture container images from the live server, ensuring the ISO includes the same set of applications as the dev server. - Revised deployment documentation to stress the importance of building the Rust backend on the Linux dev server and included new instructions for capturing system-level changes for ISO builds. - Improved UI components and added new bundled applications (BTCPay Server, Mempool Explorer, Nostr Relay, Strfry Relay, Tailscale) to enhance user experience.
180 lines
6.1 KiB
Plaintext
180 lines
6.1 KiB
Plaintext
---
|
|
description: Development workflow and deployment practices for Archipelago
|
|
alwaysApply: true
|
|
---
|
|
|
|
# Archipelago Development Workflow
|
|
|
|
## Deployment Strategy
|
|
|
|
**Always deploy to live system for testing** - The target device (192.168.1.228) is a development machine, so deploy changes directly to the live system rather than using dev servers.
|
|
|
|
### Backend: build on server via rsync (never on macOS)
|
|
- **Always** deploy backend by: (1) rsync `core/` to `archipelago@192.168.1.228:~/archy/core/`, then (2) SSH and run `cargo build --release` on the server, then copy binary to `/usr/local/bin/` and restart `archipelago.service`.
|
|
- Use `sshpass -p "archipelago"` for non-interactive rsync/SSH. **Action these builds** when making backend changes; do not build the Rust binary on macOS and copy it (causes Exec format error on Linux).
|
|
|
|
### Standard Deployment Command
|
|
|
|
```bash
|
|
./scripts/deploy-to-target.sh --live
|
|
```
|
|
|
|
This command:
|
|
1. Syncs code from local Mac to remote target
|
|
2. Builds frontend (Vue.js) and backend (Rust)
|
|
3. Deploys to live paths:
|
|
- Frontend: `/opt/archipelago/web-ui/`
|
|
- Backend: `/usr/local/bin/archipelago`
|
|
4. Restarts services (systemd + nginx)
|
|
|
|
### Target Environment
|
|
|
|
- **Host**: archipelago@192.168.1.228
|
|
- **OS**: Debian-based server
|
|
- **Container Runtime**: Podman (root context for system services)
|
|
- **Web Server**: Nginx
|
|
- **Backend**: Systemd service (`archipelago.service`) running as root
|
|
|
|
## SSH Key Management
|
|
|
|
The deployment scripts require SSH key authentication. If you encounter `Permission denied` errors:
|
|
|
|
1. Ensure SSH key is loaded: `ssh-add -l`
|
|
2. Add key if needed: `ssh-add ~/.ssh/id_ed25519`
|
|
3. Enter passphrase when prompted
|
|
|
|
## Development Paths
|
|
|
|
### Local (Mac)
|
|
- Project root: `/Users/dorian/Projects/archy`
|
|
- Frontend: `neode-ui/`
|
|
- Backend: `core/`
|
|
- Scripts: `scripts/`
|
|
- ISO Build: `image-recipe/`
|
|
|
|
### Remote (Target)
|
|
- Dev directory: `~/archy/`
|
|
- Live frontend: `/opt/archipelago/web-ui/`
|
|
- Live backend: `/usr/local/bin/archipelago`
|
|
- Data: `/var/lib/archipelago/`
|
|
- Systemd service: `/etc/systemd/system/archipelago.service`
|
|
- Nginx config: `/etc/nginx/sites-available/archipelago`
|
|
|
|
## Testing Workflow
|
|
|
|
1. Make changes locally
|
|
2. Deploy with `--live` flag
|
|
3. Test at http://192.168.1.228
|
|
4. Check logs if needed:
|
|
- Backend: `ssh archipelago@192.168.1.228 'sudo journalctl -u archipelago -f'`
|
|
- Nginx: `ssh archipelago@192.168.1.228 'sudo tail -f /var/log/nginx/error.log'`
|
|
5. **Sync changes back to ISO build** (see below)
|
|
|
|
## Running Containers
|
|
|
|
Check container status:
|
|
```bash
|
|
ssh archipelago@192.168.1.228 'sudo podman ps'
|
|
```
|
|
|
|
Common containers:
|
|
- Home Assistant (port 8123)
|
|
- Bitcoin Knots (ports 8332, 8333)
|
|
- LND (ports 9735, 10009)
|
|
|
|
## ISO Build Integration
|
|
|
|
**CRITICAL**: After testing on the live server, always update the ISO build to include your changes.
|
|
|
|
### Building the ISO
|
|
|
|
**Recommended**: Build on the target server (has all dependencies):
|
|
|
|
```bash
|
|
# SSH to target server
|
|
ssh archipelago@192.168.1.228
|
|
|
|
# Navigate to project
|
|
cd ~/archy/image-recipe
|
|
|
|
# Run build with sudo (auto-installs missing deps like xorriso)
|
|
sudo ./build-auto-installer-iso.sh
|
|
|
|
# The ISO will be at: results/archipelago-auto-installer-*.iso
|
|
|
|
# Copy back to Mac
|
|
# On your Mac:
|
|
scp archipelago@192.168.1.228:~/archy/image-recipe/results/archipelago-auto-installer-*.iso .
|
|
```
|
|
|
|
**Alternative**: Build from Mac (requires Docker Desktop installed).
|
|
|
|
### Common ISO Build Issues
|
|
|
|
- **Missing xorriso**: Run with `sudo` to auto-install, or: `sudo apt install -y xorriso`
|
|
- **Missing podman**: Run with `sudo` to auto-install, or: `sudo apt install -y podman`
|
|
- **No Docker on Mac**: Either install Docker Desktop or build on target server (recommended)
|
|
|
|
### System Configuration Files to Sync
|
|
|
|
When you make system-level changes on the live server, capture them for the ISO build:
|
|
|
|
1. **Systemd Service** (`/etc/systemd/system/archipelago.service`)
|
|
- Location in repo: `image-recipe/configs/archipelago.service`
|
|
- Capture command: `ssh archipelago@192.168.1.228 'sudo cat /etc/systemd/system/archipelago.service' > image-recipe/configs/archipelago.service`
|
|
|
|
2. **Nginx Configuration** (`/etc/nginx/sites-available/archipelago`)
|
|
- Location in repo: `image-recipe/configs/nginx-archipelago.conf`
|
|
- Capture command: `ssh archipelago@192.168.1.228 'sudo cat /etc/nginx/sites-available/archipelago' > image-recipe/configs/nginx-archipelago.conf`
|
|
|
|
3. **Other System Files**
|
|
- Logrotate: `image-recipe/configs/logrotate.conf`
|
|
- Any new scripts in `/opt/archipelago/scripts/`
|
|
|
|
### Build Process Checklist
|
|
|
|
Before building a new ISO, ensure:
|
|
|
|
- [ ] Latest backend built: `cd image-recipe && ./scripts/build-backend.sh`
|
|
- [ ] Latest frontend built: `cd image-recipe && ./scripts/build-frontend.sh`
|
|
- [ ] System configs synced from live server
|
|
- [ ] Integration script updated: `./integrate-archipelago.sh`
|
|
- [ ] ISO built: `./build-debian-iso.sh`
|
|
- [ ] ISO tested in QEMU: `./test-iso-qemu.sh`
|
|
|
|
### Key Configuration Values
|
|
|
|
**Backend Service (archipelago.service)**:
|
|
- **User**: `root` (required to access root Podman containers)
|
|
- **Environment**:
|
|
- `ARCHIPELAGO_BIND=0.0.0.0:5678`
|
|
- `ARCHIPELAGO_DEV_MODE=true` (for container auto-detection)
|
|
|
|
**Nginx Configuration**:
|
|
- Serves frontend from `/opt/archipelago/web-ui`
|
|
- Proxies `/rpc/` to backend at `127.0.0.1:5678`
|
|
- Proxies `/ws` for WebSocket connections
|
|
|
|
### Deployment Paths in ISO
|
|
|
|
The ISO build must install files to:
|
|
- `/usr/local/bin/archipelago` - Backend binary
|
|
- `/opt/archipelago/web-ui/` - Frontend files
|
|
- `/etc/systemd/system/archipelago.service` - Service definition
|
|
- `/etc/nginx/sites-available/archipelago` - Nginx config
|
|
- `/opt/archipelago/` - Base directory for scripts and data
|
|
|
|
## Common Issues
|
|
|
|
### Container Detection
|
|
- Containers must be in **root Podman context** (started with `sudo podman`)
|
|
- Backend must run as **root** to see root containers
|
|
- Check: `sudo podman ps` (should show containers)
|
|
- Check: `podman ps` (should be empty if using root containers)
|
|
|
|
### Service Not Starting
|
|
- Check systemd status: `sudo systemctl status archipelago`
|
|
- Check logs: `sudo journalctl -u archipelago -n 50`
|
|
- Verify binary: `ls -lh /usr/local/bin/archipelago`
|
|
- Test manually: `sudo /usr/local/bin/archipelago`
|