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