krops-lamassu/docs/install.md

Installation Guide

This guide walks you through deploying a Lamassu Bitcoin ATM server using nix-bitcoin with 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:

   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)

# 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)

# 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

nixos-generate-config --root /mnt

Enable SSH Access

Edit /mnt/etc/nixos/configuration.nix to add:

services.openssh.enable = true;
users.users.root.openssh.authorizedKeys.keys = [
  "ssh-ed25519 AAAA... your-key-here"
];

Install NixOS

nixos-install
reboot

2. Install Nix on Your Deployment Machine

If Nix is not already installed on your local machine:

# Install Nix (multi-user installation recommended)
sh <(curl -L https://nixos.org/nix/install) --daemon

After installation, restart your shell or run:

. /etc/profile.d/nix.sh

3. Clone This Repository

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:

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:

target = "root@your-node-ip-or-hostname";

Configure Hardware

Copy the hardware configuration from your target machine:

scp root@your-node:/etc/nixos/hardware-configuration.nix config/

Or generate it remotely:

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:

   networking.hostName = "my-bitcoin-node";
   

2. Set your timezone:

   time.timeZone = "UTC";
   

3. Add your SSH public key:

   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:

./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:

./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:

# 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:

./deploy.sh

Or equivalently:

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:

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:

# 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:

journalctl -u lamassu-server -f
journalctl -u lamassu-admin-server -f
journalctl -u lamassu-build -f

Further Reading

• nix-bitcoin documentation
• NixOS manual
• krops documentation