docs: add machine installation guide
Comprehensive deployment documentation for Sintra including: - Build instructions - AppImage and unpacked deployment options - Environment variable configuration - Systemd service setup for auto-start - Hardware verification steps - Troubleshooting guide Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Patrick Mulligan
parent
55d963904c
commit
6371244b46
1 changed files with 270 additions and 0 deletions
270
lamassu-next/docs/machine-installation.md
Normal file
270
lamassu-next/docs/machine-installation.md
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
# Machine Installation
|
||||
|
||||
This document describes how to deploy the Lamassu Next ATM software to a Sintra machine.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### On the Sintra
|
||||
|
||||
- Linux OS with X11 display server
|
||||
- Network connectivity (WiFi or Ethernet)
|
||||
- User account with `dialout` group membership (for serial port access)
|
||||
|
||||
### Backend Services
|
||||
|
||||
The ATM requires network access to:
|
||||
|
||||
| Service | Purpose | Required |
|
||||
| ------------- | ------------------- | -------- |
|
||||
| Nostr relay | CLINK communication | Yes |
|
||||
| Lightning.Pub | Payment processing | Yes |
|
||||
|
||||
These can be self-hosted or provided by a third party.
|
||||
|
||||
## Building the Application
|
||||
|
||||
### Development Machine Setup
|
||||
|
||||
1. Enter the development environment:
|
||||
|
||||
```bash
|
||||
cd lamassu-next
|
||||
devenv shell
|
||||
```
|
||||
|
||||
2. Build the Electron application:
|
||||
|
||||
```bash
|
||||
cd apps/machine
|
||||
pnpm build:electron
|
||||
```
|
||||
|
||||
3. Build artifacts are created in `apps/machine/release/`:
|
||||
|
||||
```
|
||||
release/
|
||||
├── Lamassu ATM-0.1.0.AppImage # Portable executable (recommended)
|
||||
└── linux-unpacked/ # Unpacked application directory
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Option A: AppImage (Recommended)
|
||||
|
||||
The AppImage is a self-contained executable that works on any Linux distribution.
|
||||
|
||||
1. Copy to Sintra:
|
||||
|
||||
```bash
|
||||
scp "apps/machine/release/Lamassu ATM-0.1.0.AppImage" user@sintra:/opt/lamassu/
|
||||
```
|
||||
|
||||
2. Make executable:
|
||||
|
||||
```bash
|
||||
ssh user@sintra
|
||||
chmod +x "/opt/lamassu/Lamassu ATM-0.1.0.AppImage"
|
||||
```
|
||||
|
||||
3. Test manually:
|
||||
|
||||
```bash
|
||||
export DISPLAY=:0
|
||||
"/opt/lamassu/Lamassu ATM-0.1.0.AppImage" --no-sandbox
|
||||
```
|
||||
|
||||
### Option B: Unpacked Directory
|
||||
|
||||
For faster startup times, deploy the unpacked application:
|
||||
|
||||
1. Copy to Sintra:
|
||||
|
||||
```bash
|
||||
scp -r apps/machine/release/linux-unpacked user@sintra:/opt/lamassu/
|
||||
```
|
||||
|
||||
2. Test manually:
|
||||
|
||||
```bash
|
||||
ssh user@sintra
|
||||
export DISPLAY=:0
|
||||
/opt/lamassu/linux-unpacked/lamassu-machine --no-sandbox
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a configuration file at `/opt/lamassu/.env`:
|
||||
|
||||
```bash
|
||||
# Machine model (sintra, gaia, or custom)
|
||||
VITE_LAMASSU_MACHINE_MODEL=sintra
|
||||
|
||||
# Fiat currency code (ISO 4217)
|
||||
VITE_LAMASSU_FIAT_CODE=USD
|
||||
|
||||
# Custom device paths (optional, uses preset defaults if not set)
|
||||
# VITE_LAMASSU_VALIDATOR_DEVICE=/dev/ttyJ5
|
||||
# VITE_LAMASSU_DISPENSER_DEVICE=/dev/ttyJ7
|
||||
|
||||
# Cassette configuration (optional)
|
||||
# VITE_LAMASSU_CASSETTES='[{"denomination":20,"count":100}]'
|
||||
```
|
||||
|
||||
See [Device Configuration](./device-configuration.md) for detailed configuration options.
|
||||
|
||||
### Lightning.Pub Connection
|
||||
|
||||
The ATM needs to connect to a Lightning.Pub instance. Configure via environment:
|
||||
|
||||
```bash
|
||||
# Nostr relay URL
|
||||
VITE_NOSTR_RELAY_URL=wss://your-relay.example.com
|
||||
|
||||
# Lightning.Pub public key
|
||||
VITE_LIGHTNING_PUB_PUBKEY=npub1...
|
||||
|
||||
# ATM keypair (generate with: npx @lamassu/nostr-client generate-keypair)
|
||||
VITE_ATM_NSEC=nsec1...
|
||||
```
|
||||
|
||||
## Auto-Start on Boot
|
||||
|
||||
### Systemd Service
|
||||
|
||||
Create `/etc/systemd/system/lamassu-kiosk.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Lamassu ATM Kiosk
|
||||
After=graphical.target network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=lamassu
|
||||
Environment=DISPLAY=:0
|
||||
EnvironmentFile=/opt/lamassu/.env
|
||||
WorkingDirectory=/opt/lamassu
|
||||
ExecStart=/opt/lamassu/linux-unpacked/lamassu-machine --no-sandbox
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=graphical.target
|
||||
```
|
||||
|
||||
Enable and start:
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable lamassu-kiosk
|
||||
sudo systemctl start lamassu-kiosk
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
sudo systemctl status lamassu-kiosk
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u lamassu-kiosk -f
|
||||
|
||||
# Restart after configuration changes
|
||||
sudo systemctl restart lamassu-kiosk
|
||||
```
|
||||
|
||||
## Hardware Verification
|
||||
|
||||
### Serial Port Access
|
||||
|
||||
1. Verify devices exist:
|
||||
|
||||
```bash
|
||||
ls -la /dev/ttyJ*
|
||||
# Expected: /dev/ttyJ4 (printer), /dev/ttyJ5 (validator), /dev/ttyJ7 (dispenser)
|
||||
```
|
||||
|
||||
2. Check user permissions:
|
||||
|
||||
```bash
|
||||
groups
|
||||
# Should include 'dialout'
|
||||
```
|
||||
|
||||
3. If not in dialout group:
|
||||
|
||||
```bash
|
||||
sudo usermod -a -G dialout $USER
|
||||
# Logout and login for changes to take effect
|
||||
```
|
||||
|
||||
### Display Configuration
|
||||
|
||||
The Sintra uses a 1080x1920 portrait display. Verify X11 is running:
|
||||
|
||||
```bash
|
||||
echo $DISPLAY
|
||||
# Should output :0 or similar
|
||||
|
||||
xdpyinfo | head -5
|
||||
# Should show display information
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Application Won't Start
|
||||
|
||||
1. **Missing display**: Ensure `DISPLAY=:0` is set
|
||||
2. **Sandbox error**: Use `--no-sandbox` flag
|
||||
3. **Permission denied**: Check file is executable (`chmod +x`)
|
||||
|
||||
### Hardware Not Responding
|
||||
|
||||
1. **Check serial ports exist**: `ls -la /dev/ttyJ*`
|
||||
2. **Check permissions**: User must be in `dialout` group
|
||||
3. **Check connections**: Ensure cables are properly seated
|
||||
4. **Power cycle hardware**: Turn validator/dispenser off and on
|
||||
|
||||
### Network Issues
|
||||
|
||||
1. **Test relay connection**: `websocat wss://your-relay.example.com`
|
||||
2. **Check DNS resolution**: `ping your-relay.example.com`
|
||||
3. **Verify firewall**: Ensure outbound WebSocket connections allowed
|
||||
|
||||
### Logs
|
||||
|
||||
Application logs are written to:
|
||||
|
||||
- **Systemd**: `journalctl -u lamassu-kiosk`
|
||||
- **Electron**: `~/.config/lamassu-machine/logs/`
|
||||
|
||||
## Updating
|
||||
|
||||
1. Build new version on development machine
|
||||
2. Stop the service:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop lamassu-kiosk
|
||||
```
|
||||
|
||||
3. Replace application files:
|
||||
|
||||
```bash
|
||||
scp -r apps/machine/release/linux-unpacked/* user@sintra:/opt/lamassu/linux-unpacked/
|
||||
```
|
||||
|
||||
4. Restart service:
|
||||
|
||||
```bash
|
||||
sudo systemctl start lamassu-kiosk
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
- The `--no-sandbox` flag is required for Electron on some Linux configurations. This is acceptable for a dedicated kiosk machine.
|
||||
- Keep the ATM's nsec private key secure. It authorizes all transactions from this machine.
|
||||
- Use a dedicated user account (`lamassu`) with minimal privileges.
|
||||
- Consider firewall rules to restrict network access to only required services.
|
||||
Loading…
Add table
Add a link
Reference in a new issue