Initial commit: krops-lamassu deployment template
NixOS deployment template for Lamassu Bitcoin ATM server using nix-bitcoin and krops. Features: - Lamassu server with PostgreSQL and auto-generated secrets - TLS certificates (self-signed) - Test VM for local development - Template structure for easy customization
This commit is contained in:
commit
6febf28955
11 changed files with 1094 additions and 0 deletions
313
docs/install.md
Normal file
313
docs/install.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
# Installation Guide
|
||||
|
||||
This guide walks you through deploying a [Lamassu Bitcoin ATM server](https://github.com/lamassu/lamassu-server) using [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) with [krops](https://cgit.krebsco.de/krops/) deployment.
|
||||
|
||||
The deployment is managed from your local machine and pushed to the target server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A target machine with NixOS installed (or ready for installation)
|
||||
- SSH access to the target machine as root
|
||||
- Nix installed on your local deployment machine
|
||||
|
||||
## 0. Preparation
|
||||
|
||||
### Hardware Requirements
|
||||
|
||||
Any modern computer will work. Recommended minimum specs:
|
||||
- 2+ CPU cores
|
||||
- 4GB+ RAM (8GB+ recommended for full node with electrs)
|
||||
- 1TB+ SSD for full blockchain (or use pruning for less)
|
||||
|
||||
### Security Considerations (Optional)
|
||||
|
||||
For enhanced security, consider:
|
||||
- Disabling SMT (Simultaneous Multi-Threading) in BIOS to mitigate speculative execution attacks
|
||||
- Using full disk encryption
|
||||
- Enabling the hardened kernel preset (see `configuration.nix`)
|
||||
|
||||
## 1. Install NixOS on Target Machine
|
||||
|
||||
If NixOS is not already installed on your target machine:
|
||||
|
||||
1. Download the NixOS minimal ISO from https://nixos.org/download/
|
||||
2. Write it to a USB drive:
|
||||
```bash
|
||||
sudo dd if=nixos-minimal-*.iso of=/dev/sdX bs=4M status=progress
|
||||
```
|
||||
3. Boot the target machine from the USB drive
|
||||
4. Partition and format your drives
|
||||
|
||||
### Partitioning (UEFI)
|
||||
|
||||
```bash
|
||||
# Create GPT partition table
|
||||
parted /dev/sda -- mklabel gpt
|
||||
|
||||
# Create EFI boot partition (512MB)
|
||||
parted /dev/sda -- mkpart ESP fat32 1MiB 512MiB
|
||||
parted /dev/sda -- set 1 esp on
|
||||
|
||||
# Create root partition (rest of disk)
|
||||
parted /dev/sda -- mkpart primary 512MiB 100%
|
||||
|
||||
# Format partitions
|
||||
mkfs.fat -F 32 -n boot /dev/sda1
|
||||
mkfs.ext4 -L nixos /dev/sda2
|
||||
|
||||
# Mount partitions
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
mkdir -p /mnt/boot
|
||||
mount /dev/disk/by-label/boot /mnt/boot
|
||||
```
|
||||
|
||||
### Partitioning (Legacy BIOS/MBR)
|
||||
|
||||
```bash
|
||||
# Create MBR partition table
|
||||
parted /dev/sda -- mklabel msdos
|
||||
|
||||
# Create root partition
|
||||
parted /dev/sda -- mkpart primary 1MiB 100%
|
||||
parted /dev/sda -- set 1 boot on
|
||||
|
||||
# Format partition
|
||||
mkfs.ext4 -L nixos /dev/sda1
|
||||
|
||||
# Mount partition
|
||||
mount /dev/disk/by-label/nixos /mnt
|
||||
```
|
||||
|
||||
### Generate Initial Configuration
|
||||
|
||||
```bash
|
||||
nixos-generate-config --root /mnt
|
||||
```
|
||||
|
||||
### Enable SSH Access
|
||||
|
||||
Edit `/mnt/etc/nixos/configuration.nix` to add:
|
||||
|
||||
```nix
|
||||
services.openssh.enable = true;
|
||||
users.users.root.openssh.authorizedKeys.keys = [
|
||||
"ssh-ed25519 AAAA... your-key-here"
|
||||
];
|
||||
```
|
||||
|
||||
### Install NixOS
|
||||
|
||||
```bash
|
||||
nixos-install
|
||||
reboot
|
||||
```
|
||||
|
||||
## 2. Install Nix on Your Deployment Machine
|
||||
|
||||
If Nix is not already installed on your local machine:
|
||||
|
||||
```bash
|
||||
# Install Nix (multi-user installation recommended)
|
||||
sh <(curl -L https://nixos.org/nix/install) --daemon
|
||||
```
|
||||
|
||||
After installation, restart your shell or run:
|
||||
```bash
|
||||
. /etc/profile.d/nix.sh
|
||||
```
|
||||
|
||||
## 3. Clone This Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR-USERNAME/krops-lamassu.git
|
||||
cd krops-lamassu
|
||||
```
|
||||
|
||||
## 4. Copy Example Files
|
||||
|
||||
Copy the template files to create your local configuration:
|
||||
|
||||
```bash
|
||||
cp example/krops.nix ./krops.nix
|
||||
cp -r example/config ./config
|
||||
```
|
||||
|
||||
Your `krops.nix` and `config/` are gitignored, so you can pull upstream changes without conflicts.
|
||||
|
||||
## 5. Configure Your Deployment
|
||||
|
||||
### Set Target Host
|
||||
|
||||
Edit `krops.nix` and set your target:
|
||||
|
||||
```nix
|
||||
target = "root@your-node-ip-or-hostname";
|
||||
```
|
||||
|
||||
### Configure Hardware
|
||||
|
||||
Copy the hardware configuration from your target machine:
|
||||
|
||||
```bash
|
||||
scp root@your-node:/etc/nixos/hardware-configuration.nix config/
|
||||
```
|
||||
|
||||
Or generate it remotely:
|
||||
|
||||
```bash
|
||||
ssh root@your-node nixos-generate-config --show-hardware-config > config/hardware-configuration.nix
|
||||
```
|
||||
|
||||
### Configure Boot Loader
|
||||
|
||||
Edit `config/boot.nix`:
|
||||
|
||||
- **UEFI systems**: Keep the default systemd-boot configuration
|
||||
- **Legacy BIOS**: Comment out systemd-boot and enable GRUB
|
||||
|
||||
### Configure Services
|
||||
|
||||
Edit `config/configuration.nix`:
|
||||
|
||||
1. Set your hostname:
|
||||
```nix
|
||||
networking.hostName = "my-bitcoin-node";
|
||||
```
|
||||
|
||||
2. Set your timezone:
|
||||
```nix
|
||||
time.timeZone = "UTC";
|
||||
```
|
||||
|
||||
3. Add your SSH public key:
|
||||
```nix
|
||||
users.users.root.openssh.authorizedKeys.keys = [
|
||||
"ssh-ed25519 AAAA... your-key"
|
||||
];
|
||||
```
|
||||
|
||||
4. Enable desired services by uncommenting them (e.g., `services.lnd.enable`, `services.electrs.enable`)
|
||||
|
||||
## 6. Test Your Configuration
|
||||
|
||||
Before deploying, test that your configuration builds successfully:
|
||||
|
||||
```bash
|
||||
./deploy.sh test
|
||||
```
|
||||
|
||||
This builds the configuration locally without deploying.
|
||||
|
||||
## 7. Run a Test VM (Optional)
|
||||
|
||||
You can test your setup in a VM before deploying to real hardware:
|
||||
|
||||
```bash
|
||||
./deploy.sh vm
|
||||
```
|
||||
|
||||
This starts a QEMU VM with:
|
||||
- Lamassu server with auto-generated secrets
|
||||
- PostgreSQL database configured
|
||||
- Auto-login to root console
|
||||
- Port forwarding to host
|
||||
|
||||
Access the services from your host:
|
||||
- **Admin UI**: https://localhost:8443
|
||||
- **Server API**: https://localhost:3000
|
||||
|
||||
From other machines on your LAN, use your host's IP (e.g., `https://192.168.1.50:8443`).
|
||||
|
||||
Note: You'll see a certificate warning (self-signed cert) - accept it to proceed.
|
||||
|
||||
Useful commands inside the VM:
|
||||
```bash
|
||||
# Watch build progress (first run takes several minutes)
|
||||
journalctl -fu lamassu-build
|
||||
|
||||
# Check service status
|
||||
systemctl status lamassu-server lamassu-admin-server
|
||||
|
||||
# View generated secrets
|
||||
ls -la /secrets/
|
||||
```
|
||||
|
||||
To exit the VM, run `shutdown now` in the VM console.
|
||||
|
||||
## 8. Deploy to Target
|
||||
|
||||
When ready, deploy to your target machine:
|
||||
|
||||
```bash
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
Or equivalently:
|
||||
```bash
|
||||
nix-shell --run 'nix-build krops.nix -A deploy --no-out-link && ./result'
|
||||
```
|
||||
|
||||
The first deployment will take longer as it downloads and builds all packages.
|
||||
|
||||
## 9. Verify Deployment
|
||||
|
||||
SSH into your server and check service status:
|
||||
|
||||
```bash
|
||||
ssh root@your-server
|
||||
|
||||
# Check Lamassu services
|
||||
systemctl status lamassu-server lamassu-admin-server
|
||||
|
||||
# Watch build progress (first run takes several minutes)
|
||||
journalctl -fu lamassu-build
|
||||
|
||||
# View generated secrets
|
||||
ls -la /secrets/
|
||||
```
|
||||
|
||||
Access the admin UI at `https://YOUR-SERVER-IP` (you'll see a certificate warning for the self-signed cert).
|
||||
|
||||
## Updating Your Node
|
||||
|
||||
To update nix-bitcoin to a new release:
|
||||
|
||||
1. Edit `config/nix-bitcoin-release.nix` with the new version
|
||||
2. Run `./deploy.sh`
|
||||
|
||||
Find releases at: https://github.com/fort-nix/nix-bitcoin/releases
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Build Failures
|
||||
|
||||
If the build fails, try:
|
||||
```bash
|
||||
# Clean Nix store garbage
|
||||
nix-collect-garbage -d
|
||||
|
||||
# Rebuild with more verbose output
|
||||
nix-build krops.nix -A test --show-trace
|
||||
```
|
||||
|
||||
### SSH Connection Issues
|
||||
|
||||
Ensure:
|
||||
- Target machine is reachable: `ping your-node`
|
||||
- SSH key is correct: `ssh -v root@your-node`
|
||||
- Firewall allows SSH (port 22)
|
||||
|
||||
### Service Issues
|
||||
|
||||
Check logs on the target:
|
||||
```bash
|
||||
journalctl -u lamassu-server -f
|
||||
journalctl -u lamassu-admin-server -f
|
||||
journalctl -u lamassu-build -f
|
||||
```
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [nix-bitcoin documentation](https://github.com/fort-nix/nix-bitcoin/tree/master/docs)
|
||||
- [NixOS manual](https://nixos.org/manual/nixos/stable/)
|
||||
- [krops documentation](https://cgit.krebsco.de/krops/)
|
||||
Loading…
Add table
Add a link
Reference in a new issue