This guide covers everything you need to prepare before you can start building your NixOS configuration. It includes hardware requirements, initial server setup, DNS configuration, and security basics.
For a basic setup running 5-10 services:
For running all 14+ services with multiple users:
Per-service resource estimates:
Total: Approximately 3.5-4 GB RAM at steady state with all services running.
VPS Providers:
Recommended: UpCloud - UpCloud provides NixOS 24.11 and 25.05 Minimal Installation CDs as preloaded images, making installation straightforward. They also offer excellent support and competitive pricing starting at €3/month for 1 CPU, 1GB RAM, 10GB storage.
Minimum Requirements from Provider:
Order your VPS with:
You'll receive credentials via email:
root)First login via password:
ssh root@your-server-ip
# You'll be prompted for the password
}}}
*Immediate security steps:*# Update the system
apt update && apt upgrade -y
# Install essential tools
apt install -y vim git curl wget htop
# Set a strong root password (if not already set)
passwd
}}}
On your local machine, generate an SSH key pair if you don't have one:
# Check if you already have keys
ls ~/.ssh/id_*.pub
# If not, generate a new key (use ed25519 for best security)
ssh-keygen -t ed25519 -C "your-email@example.com"
# Press Enter to accept default location
# Set a passphrase (recommended) or press Enter twice for no passphrase
}}}
*Copy your public key to the server:*# From your local machine
ssh-copy-id root@your-server-ip
# Enter your root password when prompted
}}}
Verify key login works:
ssh root@your-server-ip
# Should log in without password prompt
}}}
*Disable password authentication (security hardening):*# On the server, edit SSH config
vim /etc/ssh/sshd_config
# Set these options:
PermitRootLogin prohibit-password
PasswordAuthentication no
PubkeyAuthentication yes
# Restart SSH
systemctl restart sshd
}}}
Test in a new terminal before closing current session!
You need to configure these DNS A records pointing to your server IP:
; Root domain
snek.cc. A YOUR_SERVER_IP
; Main subdomains
knot.snek.cc. A YOUR_SERVER_IP
spindle.snek.cc. A YOUR_SERVER_IP
lycan.snek.cc. A YOUR_SERVER_IP
grafana.snek.cc. A YOUR_SERVER_IP
; PDS wildcard (for user subdomains)
*.pds.snek.cc. A YOUR_SERVER_IP
pds.snek.cc. A YOUR_SERVER_IP
; Short aliases
sd.snek.cc. A YOUR_SERVER_IP ; spacedust
sp.snek.cc. A YOUR_SERVER_IP ; spindle
ly.snek.cc. A YOUR_SERVER_IP ; lycan
; Optional services
constellation.snek.cc. A YOUR_SERVER_IP
quickdid.snek.cc. A YOUR_SERVER_IP
slingshot.snek.cc. A YOUR_SERVER_IP
}}}
=== Setting Up DNS ===
*Using Cloudflare (recommended):*
1. Create account at [[https://cloudflare.com|cloudflare.com]]
2. Add your domain
3. Change nameservers at your registrar to Cloudflare's
4. Add A records in the DNS section
5. Set proxy status to "DNS only" (grey cloud) initially
*Using your registrar's DNS:*
1. Log into your domain registrar
2. Find DNS management section
3. Add A records as shown above
4. Save changes
=== Verify DNS ===
Wait 5-30 minutes for propagation, then verify:# Check each domain
dig +short snek.cc
dig +short knot.snek.cc
dig +short anything.pds.snek.cc # Should all return your IP
# Or use nslookup
nslookup snek.cc
}}}
SSH uses public-key cryptography:
If you have multiple servers, you can create a key specifically for this server:
# Generate server-specific key
ssh-keygen -t ed25519 -f ~/.ssh/snek_ed25519 -C "snek server access"
# Use it explicitly when connecting
ssh -i ~/.ssh/snek_ed25519 root@snek.cc
# Or add to SSH config for automatic use
vim ~/.ssh/config
}}}
Add to `~/.ssh/config`:Host snek
HostName snek.cc
User atproto
IdentityFile ~/.ssh/snek_ed25519
IdentitiesOnly yes
}}}
Then connect with:
ssh snek
}}}
== Installing NixOS ==
You have two options for installing NixOS:
=== Option A: Fresh NixOS Install (Recommended) ===
This gives you a pure NixOS system from the ground up.
*Prerequisites:*
- Ability to boot from ISO image
- KVM access or virtual console from your provider
*Steps:*
1. *Download NixOS ISO:*
Download the minimal 64-bit ISO from [[https://nixos.org/download|nixos.org/download]]
2. *Mount ISO:*
- In your provider's control panel
- Attach the ISO to your VPS
- Reboot into the ISO
3. *Follow NixOS Installation:*
{{<
# Once booted into NixOS installer
# Partition, format, and mount your disks
# Generate hardware configuration
# Install NixOS
# See official guide: https://nixos.org/manual/nixos/stable/#sec-installation
}}
4. *Detailed Steps:*
Refer to the official NixOS Installation Guide:
[[https://nixos.org/manual/nixos/stable/#sec-installation|NixOS Installation Guide]]
=== Option B: Install NixOS Tools on Existing Linux ===
Use tools like `nixos-anywhere` to convert an existing Linux system.
*Requirements:*
- Existing Linux system (Ubuntu/Debian)
- Root access
- Nix package manager installed
*Steps:*
1. Install Nix package manager:
{{{
curl -L https://nixos.org/nix/install | sh
. ~/.nix-profile/etc/profile.d/nix.sh
}}}
2. Use nixos-anywhere (advanced):
See [[https://github.com/nix-community/nixos-anywhere|nixos-anywhere documentation]]
=== Option C: Use NixOS-friendly Provider ===
Some providers offer NixOS as a base image:
- *UpCloud* - NixOS 24.11 and 25.05 ISOs preloaded (recommended!)
- *Hetzner Cloud* - NixOS image available
- *DigitalOcean* - Community NixOS image
- *Vultr* - Custom ISO upload
Choose this for easiest setup.
== UpCloud NixOS Installation (Recommended Method) ==
UpCloud provides the best NixOS installation experience with preloaded NixOS installation ISOs.
=== Step 1: Create UpCloud Account ===
1. Go to [[https://upcloud.com|upcloud.com]] and create an account
2. Verify your email and complete account setup
3. Add a payment method (credit card or PayPal)
4. You'll get free trial credits to start
=== Step 2: Deploy NixOS Server ===
1. Go to [[https://hub.upcloud.com/deploy|hub.upcloud.com/deploy]]
2. Select your data center location (Helsinki, Frankfurt, London, etc.)
3. Choose a plan:
- *Minimum for testing:* 1 CPU, 1GB RAM, 10GB storage (~€3/month)
- *Recommended for production:* 2 CPU, 4GB RAM, 80GB storage (~€20/month)
- *Note:* NixOS needs at least 4GB RAM for some services
4. Under *Storage*, select *"Load from CD-ROM"*
5. Choose either:
- *NixOS 24.11 Minimal Installation CD* (stable)
- *NixOS 25.05 Minimal Installation CD* (latest)
6. Add your SSH public key (recommended)
7. Set server hostname to something descriptive (e.g., "snek-nixos")
8. Click *Deploy*
=== Step 3: Access Console and Fix Keyboard Layout ===
UpCloud's console has a keyboard layout issue where `/` and some other keys may not work. You need to fix this before proceeding:
1. Once deployment is complete, click on your server
2. Go to the *Console* tab
3. Login as `root` (no password needed for the ISO)
4. Create a custom keymap file:
{{{
vi custom.map
}}}
5. Add this content:
{{{
keycode 53 = slash slash
}}}
6. Load the keymap:
{{{
loadkeys custom.map
}}}
*Note:* This fix is temporary and only needed during installation. Once NixOS is installed, keyboard layout works normally.
=== Step 4: Partition and Install ===
*Important:* UpCloud uses BIOS boot (not UEFI), so use MBR partitioning:
# Wipe disk and create MBR partition table
parted /dev/vda -- mklabel msdos
# Create swap partition (1GB or more)
parted /dev/vda -- mkpart primary linux-swap 1MiB 1025MiB
# Create root partition (rest of disk)
parted /dev/vda -- mkpart primary ext4 1025MiB 100%
# Format partitions
mkswap /dev/vda1
swapon /dev/vda1
mkfs.ext4 /dev/vda2
# Mount root partition
mount /dev/vda2 /mnt
}}}
# Generate hardware configuration
nixos-generate-config --root /mnt
# Edit configuration
cd /mnt/etc/nixos
vi configuration.nix
}}}
Basic configuration for UpCloud:{ config, pkgs, ... }:
{
imports = [ ./hardware-configuration.nix ];
# Boot loader for BIOS
boot.loader.grub.enable = true;
boot.loader.grub.device = "/dev/vda";
# Hostname
networking.hostName = "snek";
# Enable SSH
services.openssh = {
enable = true;
settings.PasswordAuthentication = false;
settings.PermitRootLogin = "prohibit-password";
};
# Add your SSH key
users.users.root.openssh.authorizedKeys.keys = [
"ssh-ed25519 YOURPUBLICKEY_HERE"
];
# Timezone
time.timeZone = "UTC";
# Essential packages
environment.systemPackages = with pkgs; [
vim
git
wget
];
# Enable flakes
nix.settings.experimental-features = [ "nix-command" "flakes" ];
system.stateVersion = "24.11";
}
}}}
nixos-install
}}}
When prompted, set a root password. Then:# Shutdown
shutdown -h now
}}}
1. In UpCloud dashboard, go to your server
2. Click Options tab
3. Find Boot Order section
4. Change from CD-ROM first to Storage first
5. Restart the server
Once rebooted, SSH into your server:
ssh root@YOUR_SERVER_IP
}}}
Create a user account:useradd -m -G wheel -s /bin/bash atproto
passwd atproto
mkdir -p /home/atproto/.ssh
cp /root/.ssh/authorized_keys /home/atproto/.ssh/
chown -R atproto:atproto /home/atproto/.ssh
chmod 700 /home/atproto/.ssh
chmod 600 /home/atproto/.ssh/authorized_keys
}}}
Enable sudo for wheel group in /etc/nixos/configuration.nix:
security.sudo.wheelNeedsPassword = false;
}}}
Rebuild:nixos-rebuild switch
}}}
If you already have a Debian server on UpCloud, you can convert it to NixOS using kexec:
# SSH into your Debian server
ssh root@your-server-ip
# Download and run NixOS kexec installer
curl -sL https://github.com/nix-community/nixos-images/releases/latest/download/nixos-kexec-installer-noninteractive-x86_64-linux.tar.gz | tar -xzf- -C /root && /root/kexec/run
# Wait 30 seconds, then reconnect (you'll be in NixOS live environment now)
ssh root@your-server-ip
# Now follow the standard NixOS installation steps from Step 4 above
}}}
=== UpCloud-Specific Notes ===
*Why UpCloud is recommended:*
- Preloaded NixOS ISOs (no custom ISO upload needed)
- Excellent support (fast response, even on weekends)
- Competitive pricing (€3/month minimum)
- Multiple data center locations
- Native NixOS support via console
*Keyboard layout issue:* The UpCloud console uses a non-standard keyboard layout where `/` key doesn't work. Use the keymap fix described in Step 3.
*BIOS boot:* UpCloud uses BIOS/MBR, not UEFI. Make sure to use `msdos` partition table and `boot.loader.grub.device = "/dev/vda"`.
*Networking:* Network works out-of-the-box with DHCP. No special configuration needed.
== Initial System Configuration ==
=== Post-Installation Setup ===
Once NixOS is installed and you've rebooted:
*1. Create User Account:*# As root, create your user
useradd -m -G wheel -s /bin/bash atproto
passwd atproto
# Set up SSH key for user
mkdir -p /home/atproto/.ssh
cp /root/.ssh/authorized_keys /home/atproto/.ssh/
chown -R atproto:atproto /home/atproto/.ssh
chmod 700 /home/atproto/.ssh
chmod 600 /home/atproto/.ssh/authorized_keys
}}}
2. Enable Flakes (Temporary):
# Edit NixOS configuration
vim /etc/nixos/configuration.nix
# Add to configuration:
# nix.settings.experimental-features = [ "nix-command" "flakes" ];
# Rebuild
nixos-rebuild switch
}}}
*3. Test Sudo:*# Switch to your user
su - atproto
# Test sudo
sudo whoami
# Should return "root"
}}}
4. Verify Basic Connectivity:
# Check network
ip addr show
ping -c 3 google.com
# Check DNS resolution
host snek.cc
# Check firewall (should be mostly closed)
iptables -L -n
}}}
== Pre-Configuration Checklist ==
Before you start writing your NixOS configuration, verify:
=== Infrastructure ===
- [ ] Server provisioned and accessible
- [ ] SSH key authentication working (no passwords)
- [ ] Root password set (emergency access)
- [ ] NixOS installed and booted
- [ ] Flakes enabled in NixOS
- [ ] User account created with sudo access
- [ ] Basic tools installed (git, vim, curl)
=== DNS ===
- [ ] Domain registered and controlled
- [ ] A record for root domain (snek.cc)
- [ ] A records for main subdomains
- [ ] Wildcard A record for *.pds.snek.cc
- [ ] DNS propagated (verified with dig/nslookup)
- [ ] Reverse DNS (PTR) set (optional but recommended)
=== Security ===
- [ ] SSH password authentication disabled
- [ ] Root login via password disabled
- [ ] Firewall default-deny configured
- [ ] Automatic security updates enabled (or plan for manual updates)
- [ ] Backup strategy planned
=== Access ===
- [ ] SSH keys backed up locally
- [ ] Provider console access tested (in case SSH fails)
- [ ] Recovery/emergency procedures documented
=== Tools ===
- [ ] Git installed locally
- [ ] SSH config set up for easy server access
- [ ] Text editor ready for writing configuration
- [ ] Age key generated (for secrets):
{{{
age-keygen -o ~/snek-age-key.txt
# Save the public key shown - you'll need it
}}}
== Next Steps ==
Once you've completed this checklist, you're ready to start building your NixOS configuration:
1. *If using UpCloud:* You already have NixOS installed! Skip to Phase 1 below
2. *If using other providers:* Follow [[#Installing NixOS|Installing NixOS]] section above
3. *Read the conceptual guides* in order (01-04)
4. *Start with Phase 1* in the Building Incrementally guide
5. *Test each component* as you add it
6. *Keep backups* of working configurations
== Troubleshooting Common Setup Issues ==
=== Can't SSH After Disabling Password Auth ===
*Symptoms:* Locked out after disabling password authentication
*Recovery:*
1. Access via provider's console (VNC/IPMI)
2. Edit `/etc/ssh/sshd_config`:
{{<
PasswordAuthentication yes
PermitRootLogin yes
}}
3. Restart SSH: `systemctl restart sshd`
4. Fix SSH keys properly
5. Re-disable password auth
=== DNS Not Propagating ===
*Symptoms:* dig/nslookup doesn't show your IP
*Solutions:*
- Wait longer (can take up to 48 hours, usually 5-30 minutes)
- Check DNS TTL settings (lower = faster propagation)
- Verify DNS records are correct at your provider
- Try different DNS servers: `dig @8.8.8.8 snek.cc`
=== NixOS Won't Boot After Install ===
*Symptoms:* System won't boot, GRUB errors
*Recovery:*
1. Boot from NixOS ISO again
2. Mount your partitions
3. Check hardware configuration
4. Reinstall if necessary
5. See [[https://nixos.org/manual/nixos/stable/#sec-troubleshooting|NixOS Troubleshooting]]
== References ==
- [[https://nixos.org/manual/nixos/stable/#sec-installation|NixOS Installation Manual]]
- [[https://wiki.nixos.org/wiki/NixOS_Installation_Guide|NixOS Installation Guide (Wiki)]]
- [[https://wiki.nixos.org/wiki/SSH_public_key_authentication|SSH Key Authentication]]
- [[https://atproto.com/guides/self-hosting|PDS Self-Hosting Requirements]]
- [[https://caddyserver.com/docs/quick-starts/reverse-proxy|Caddy Reverse Proxy Basics]]
- [[https://upcloud.com/docs/|UpCloud Documentation]]
- [[https://mrbluecoat.blogspot.com/2024/12/nixos-in-cloud.html|NixOS in the Cloud - UpCloud Guide]]
- [[https://mituuz.com/posts/2025-11-15_nixos-in-upcloud/|Setting up a NixOS server in UpCloud]]