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
e2a319f3a4
6 changed files with 506 additions and 0 deletions
21
.gitignore
vendored
Normal file
21
.gitignore
vendored
Normal file
|
|
@ -0,0 +1,21 @@
|
||||||
|
# User config files (copy from .example files)
|
||||||
|
krops.nix
|
||||||
|
config/
|
||||||
|
|
||||||
|
# Secrets - do not commit
|
||||||
|
secrets/*
|
||||||
|
!secrets/.gitkeep
|
||||||
|
|
||||||
|
# VM disk images
|
||||||
|
*.qcow2
|
||||||
|
|
||||||
|
# Nix build results
|
||||||
|
result
|
||||||
|
result-*
|
||||||
|
|
||||||
|
# Editor files
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
*~
|
||||||
|
.vscode/
|
||||||
|
.idea/
|
||||||
116
README.md
Normal file
116
README.md
Normal file
|
|
@ -0,0 +1,116 @@
|
||||||
|
# krops-lamassu
|
||||||
|
|
||||||
|
NixOS deployment template for [Lamassu Bitcoin ATM server](https://github.com/lamassu/lamassu-server) using [nix-bitcoin](https://github.com/fort-nix/nix-bitcoin) and [krops](https://cgit.krebsco.de/krops/).
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Lamassu Server** - Bitcoin ATM management system
|
||||||
|
- **PostgreSQL** - Database with auto-configured credentials
|
||||||
|
- **TLS Certificates** - Auto-generated self-signed certs
|
||||||
|
- **Secrets Management** - Automatic generation and secure storage
|
||||||
|
- **Test VM** - Local testing before production deployment
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
1. Clone this repository
|
||||||
|
2. Copy the example files:
|
||||||
|
```bash
|
||||||
|
cp example/krops.nix ./krops.nix
|
||||||
|
cp -r example/config ./config
|
||||||
|
```
|
||||||
|
3. Edit `krops.nix` to set your deployment target
|
||||||
|
4. Copy hardware config from target: `scp root@node:/etc/nixos/hardware-configuration.nix config/`
|
||||||
|
5. Edit `config/configuration.nix` to configure services
|
||||||
|
6. Deploy: `./deploy.sh`
|
||||||
|
|
||||||
|
Your `krops.nix` and `config/` are gitignored, so you can pull upstream changes without conflicts.
|
||||||
|
|
||||||
|
See [docs/install.md](docs/install.md) for detailed instructions.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
.
|
||||||
|
├── deploy.sh # Deployment script
|
||||||
|
├── shell.nix # Development shell
|
||||||
|
├── docs/
|
||||||
|
│ └── install.md # Installation guide
|
||||||
|
├── example/ # Template files (copy to get started)
|
||||||
|
│ ├── krops.nix # Krops configuration template
|
||||||
|
│ └── config/
|
||||||
|
│ ├── configuration.nix # Main NixOS configuration
|
||||||
|
│ ├── boot.nix # Bootloader config
|
||||||
|
│ ├── hardware-configuration.nix
|
||||||
|
│ └── nix-bitcoin-release.nix
|
||||||
|
├── krops.nix # Your config (gitignored)
|
||||||
|
├── config/ # Your config (gitignored)
|
||||||
|
└── secrets/ # Secrets (auto-generated, gitignored)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Deploy to target
|
||||||
|
./deploy.sh
|
||||||
|
|
||||||
|
# Test build (no deploy)
|
||||||
|
./deploy.sh test
|
||||||
|
|
||||||
|
# Run test VM with preconfigured settings
|
||||||
|
./deploy.sh vm
|
||||||
|
```
|
||||||
|
|
||||||
|
## Test VM
|
||||||
|
|
||||||
|
Run a local VM to test your configuration before deploying to production:
|
||||||
|
|
||||||
|
1. Edit the VM section in `krops.nix` and replace `127.0.0.1` with your host's IP (e.g., `192.168.1.50`)
|
||||||
|
2. Run the VM:
|
||||||
|
```bash
|
||||||
|
./deploy.sh vm
|
||||||
|
```
|
||||||
|
|
||||||
|
The VM starts with:
|
||||||
|
- Lamassu server with auto-generated secrets
|
||||||
|
- PostgreSQL database configured
|
||||||
|
- Auto-login to root console
|
||||||
|
|
||||||
|
Access the admin UI at `https://YOUR-HOST-IP:8443`
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Development Shell
|
||||||
|
|
||||||
|
Enter the nix-bitcoin development shell:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nix-shell
|
||||||
|
```
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Nix installed on deployment machine
|
||||||
|
- SSH access to target as root
|
||||||
|
- NixOS on target machine
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
- [Installation Guide](docs/install.md)
|
||||||
|
- [nix-bitcoin docs](https://github.com/fort-nix/nix-bitcoin/tree/master/docs)
|
||||||
|
- [NixOS manual](https://nixos.org/manual/nixos/stable/)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
33
deploy.sh
Executable file
33
deploy.sh
Executable file
|
|
@ -0,0 +1,33 @@
|
||||||
|
#!/usr/bin/env bash
|
||||||
|
# Deploy nix-bitcoin node
|
||||||
|
#
|
||||||
|
# Usage:
|
||||||
|
# ./deploy.sh # Build and deploy to target
|
||||||
|
# ./deploy.sh test # Test build only (no deploy)
|
||||||
|
# ./deploy.sh vm # Build and run test VM
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
cd "$(dirname "$0")"
|
||||||
|
|
||||||
|
case "${1:-deploy}" in
|
||||||
|
test)
|
||||||
|
echo "Testing build..."
|
||||||
|
nix-build krops.nix -A test --no-out-link
|
||||||
|
echo "Test build complete. Check /tmp/krops-test"
|
||||||
|
;;
|
||||||
|
vm)
|
||||||
|
echo "Building test VM..."
|
||||||
|
result=$(nix-build krops.nix -A vm --no-out-link)
|
||||||
|
echo "Starting VM..."
|
||||||
|
echo "Access admin UI at: https://localhost:8443"
|
||||||
|
"$result"/bin/run-*-vm
|
||||||
|
;;
|
||||||
|
deploy | *)
|
||||||
|
echo "Building deployment..."
|
||||||
|
result=$(nix-build krops.nix -A deploy --no-out-link)
|
||||||
|
echo "Deploying..."
|
||||||
|
"$result"
|
||||||
|
echo "Done!"
|
||||||
|
;;
|
||||||
|
esac
|
||||||
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/)
|
||||||
5
secrets/.gitkeep
Normal file
5
secrets/.gitkeep
Normal file
|
|
@ -0,0 +1,5 @@
|
||||||
|
# This directory contains secrets for nix-bitcoin services.
|
||||||
|
# Secrets are automatically generated on first deployment if not present.
|
||||||
|
#
|
||||||
|
# Do NOT commit actual secrets to version control.
|
||||||
|
# Add this directory to .gitignore or use encrypted storage.
|
||||||
18
shell.nix
Normal file
18
shell.nix
Normal file
|
|
@ -0,0 +1,18 @@
|
||||||
|
# Development shell for nix-bitcoin deployment
|
||||||
|
#
|
||||||
|
# Enter the shell with: nix-shell
|
||||||
|
#
|
||||||
|
# This provides all tools needed for deployment and management.
|
||||||
|
|
||||||
|
let
|
||||||
|
nix-bitcoin = toString (import ./config/nix-bitcoin-release.nix);
|
||||||
|
in
|
||||||
|
import "${nix-bitcoin}/helper/makeShell.nix" {
|
||||||
|
configDir = ./config;
|
||||||
|
shellVersion = "0.0.85";
|
||||||
|
|
||||||
|
# Set this to modify your shell
|
||||||
|
# extraShellInitCmds = pkgs: ''
|
||||||
|
# echo "nix-bitcoin development shell"
|
||||||
|
# '';
|
||||||
|
}
|
||||||
Loading…
Add table
Add a link
Reference in a new issue