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