34fc06726e
- Updated the Development-Workflow documentation to clarify deployment strategy, emphasizing direct deployment to the live system for testing. - Added detailed instructions for the deployment command, including syncing code, building frontend and backend, and restarting services. - Improved SSH key management section to assist with authentication issues. - Expanded the testing workflow to include steps for checking logs and syncing changes back to the ISO build. - Updated the ISO build integration section to ensure system-level changes are captured for future builds. - Refactored various sections for clarity and completeness, including deployment paths and system configuration files.
147 lines
4.8 KiB
Plaintext
147 lines
4.8 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.
|
|
|
|
### 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.
|
|
|
|
### 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`
|