Comprehensive Guide: Installing NixOS on Oracle Cloud Infrastructure (OCI) Virtual Machines

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Initial System Bootstrap
  4. Storage Configuration
  5. Base System Installation
  6. Post-Installation Configuration
  7. Advanced Configuration with Flakes
  8. Troubleshooting

Introduction

This technical guide provides detailed instructions for installing NixOS on Oracle Cloud Infrastructure (OCI) virtual machines. Since NixOS isn’t officially supported on OCI, we’ll use the kexec method to bootstrap the installation process.

Prerequisites

  • Access to an Oracle Cloud Infrastructure account
  • A running VM instance (x86_64 or aarch64 architecture)
  • Administrative (root) access to the VM
  • Basic understanding of Linux system administration
  • Familiarity with disk partitioning and SSH

Initial System Bootstrap

Step 1: Bootstrapping the NixOS Installer

Choose the appropriate architecture and execute the following commands:

# Gain root privileges
sudo -i

# For x86_64 systems
curl -L https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-kexec-installer-noninteractive-x86_64-linux.tar.gz | tar -xzf- -C /root

# For aarch64 systems
curl -L https://github.com/nix-community/nixos-images/releases/download/nixos-unstable/nixos-kexec-installer-noninteractive-aarch64-linux.tar.gz | tar -xzf- -C /root

# Execute the installer
/root/kexec/run

Note: Your SSH connection will be terminated during this process. Wait approximately 30 seconds before reconnecting.

Storage Configuration

Step 1: Disk Partitioning

The following partition scheme is recommended for optimal performance:

  • 512MB EFI System Partition (ESP)
  • Root partition (adjustable size)
  • Swap partition (typically 1GB or matched to RAM)
fdisk /dev/sda

Detailed partitioning commands:

# Create new GPT partition table
g

# Create EFI System Partition (ESP)
n
1
<Enter>
+512M

# Create root partition
n
2
<Enter>
-1G

# Create swap partition
n
3
<Enter>
<Enter>

# Mark ESP partition
t
1
uefi

# Verify partition layout
p

# Write changes
w

Step 2: Filesystem Creation

# Format ESP
mkfs.fat -F 32 -n boot /dev/sda1

# Format root partition
mkfs.ext4 -L nixos /dev/sda2

# Initialize swap
mkswap -L swap /dev/sda3

Step 3: Mount Filesystems

# Mount root filesystem
mkdir -p /mnt
mount /dev/disk/by-label/nixos /mnt

# Mount ESP
mkdir -p /mnt/boot
mount /dev/disk/by-label/boot /mnt/boot

# Activate swap
swapon /dev/sda3

Base System Installation

Step 1: Channel Configuration

nix-channel --add https://nixos.org/channels/nixos-unstable nixpkgs
nix-channel --update

Step 2: System Configuration

Generate initial configuration:

nixos-generate-config --root /mnt

Create /etc/nixos/configuration.nix:

{ config, lib, pkgs, ... }: {
  imports = [ ./hardware-configuration.nix ];

  # Bootloader configuration
  boot.loader.systemd-boot.enable = true;
  boot.loader.efi.canTouchEfiVariables = true;

  # Network configuration
  networking = {
    hostName = "nixos-oci";
    networkmanager.enable = true;
  };

  # System time configuration
  time.timeZone = "America/New_York";

  # User management
  users.users.admin = {
    isNormalUser = true;
    extraGroups = [ "wheel" ];
  };

  # Essential packages
  environment.systemPackages = with pkgs; [
    curl
    git
    vim
  ];

  # SSH configuration
  services.openssh = {
    enable = true;
    settings = {
      PermitRootLogin = "prohibit-password";
      PasswordAuthentication = false;
    };
  };

  users.users.root.openssh.authorizedKeys.keys = [
    "YOUR_SSH_PUBLIC_KEY"
  ];

  system.stateVersion = "23.11";
}

Step 3: Installation

# Install the system
nixos-install

# Set user password
nixos-enter --root "/mnt"
passwd admin

# Reboot into the new system
reboot

Post-Installation Configuration

SSH Key Configuration

# Generate SSH key
ssh-keygen -t ed25519 -C "user@example.com"

# Display public keys
cat ~/.ssh/id_ed25519.pub
cat /etc/ssh/ssh_host_ed25519_key.pub

# Add GitHub to known hosts
ssh git@github.com

Advanced Configuration with Flakes

Step 1: Clone Configuration Repository

git clone https://github.com/your-username/nixfiles
cd nixfiles

Step 2: Apply Configuration

nixos-rebuild switch --flake ".#hostname"

Troubleshooting

Common issues and their solutions:

  1. Boot failures: Verify ESP mounting and bootloader configuration
  2. Network connectivity: Check NetworkManager status and configuration
  3. SSH access issues: Verify authorized_keys permissions and content

Security Considerations

  1. Always use SSH key authentication
  2. Regularly update system packages
  3. Configure firewall rules appropriately
  4. Follow the principle of least privilege for user permissions

Performance Optimization

  1. Adjust swap size based on workload
  2. Configure appropriate filesystem options
  3. Optimize network settings for cloud environment

Note: This guide is maintained as a reference. Always refer to the official NixOS documentation for the most up-to-date information.