Nix-on-Droid Modules

Nix-on-Droid modules adapt the homelab configuration system for Android devices using Nix-on-Droid.

Overview

The Droid modules provide:

User profile integration with the home configuration system
Nix configuration optimized for mobile devices
Automatic home module imports for compatible configurations

Module Structure

modules/droid/
├── default.nix   # Module discovery and imports
├── users.nix     # User profile management
└── nixconf.nix   # Nix daemon configuration

User Management

The users module integrates Nix-on-Droid with the home configuration system.

Options

core.user.userName

string

default:"null"

The username for the Nix-on-Droid environment.

core.user.userName = "soriphoono";

core.user.shell

package

default:"pkgs.bashInteractive"

The shell to use for the user.

core.user.shell = pkgs.fish;

Home Manager Integration

When a username is set, the module automatically imports home configurations from:

homes/<username>/default.nix - Primary user configuration
homes/<username>@global/default.nix - Global settings across all platforms
homes/<username>@droid/default.nix - Droid-specific overrides

The module checks for existence and only imports paths that exist.

Shell Integration

The Fish shell is automatically enabled in Home Manager when selected:

core.user.shell = pkgs.fish;
# Automatically sets: core.shells.fish.enable = true

Example Configuration

{ pkgs, ... }: {
  core.user = {
    userName = "soriphoono";
    shell = pkgs.fish;
  };
}

This will:

Set the user shell to Fish
Import homes/soriphoono/default.nix
Import homes/soriphoono@global/default.nix (if exists)
Import homes/soriphoono@droid/default.nix (if exists)
Enable Fish shell in Home Manager

Nix Configuration

Optimized Nix daemon settings for mobile devices.

Installed Packages

environment.packages = [ pkgs.git ];

Git is installed by default for version control operations.

Nix Settings

The module configures Nix with mobile-optimized settings:

Experimental Features

experimental-features = nix-command flakes

Enables:

nix-command - New nix CLI interface
flakes - Flake support for reproducible configurations

Flake Registry

flake-registry =

Disables the global flake registry (opinionated default).

Resource Limits

cores = 2

Limits build jobs to 2 CPU cores to prevent out-of-memory errors during intensive compilations (e.g., browser builds).

Trusted Users

trusted-users = ${config.user.userName}

Grants the configured user trusted access to the Nix daemon.

Binary Caches

substituters = 
  https://cache.nixos.org
  https://nix-community.cachix.org
  https://numtide.cachix.org

trusted-public-keys =
  cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
  nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs=
  numtide.cachix.org-1:2ps1kLBUWjxIneOy1Ik6cQjb41X0iXVXeHigGmycPPE=

Configures trusted binary caches:

cache.nixos.org - Official NixOS cache
nix-community.cachix.org - Community packages
numtide.cachix.org - Numtide packages

Flake Registry and Nix Path

The module automatically syncs the flake registry and NIX_PATH with flake inputs:

nix.registry = lib.mapAttrs (_: flake: {inherit flake;}) flakeInputs;
nix.nixPath = lib.mapAttrsToList (n: _: "${n}=flake:${n}") flakeInputs;

This ensures nix-channel and legacy Nix commands work with flake inputs.

Home Module Compatibility

Nix-on-Droid can use most home modules with some adaptations:

Compatible Modules

Core Modules (with adjustments):
- Git configuration
- Secrets management
- Shell configuration (Fish, Starship)
- SSH management
User Applications:
- Development tools (Neovim, editors)
- Terminal applications
- CLI utilities

Incompatible Features

Fastfetch - Disabled on Droid (isDroid parameter)
GUI Applications - Browsers, GUI editors, desktop apps
System Services - SystemD user services (use Termux services instead)
XDG MIME types - No desktop environment integration

Droid-Specific Adaptations

Modules can detect Droid environment:

{ isDroid ? false, ... }: {
  programs.fastfetch = {
    enable = !isDroid;  # Disable on Droid
    # ...
  };
}

The isDroid parameter is passed to home modules automatically.

Complete Example

A full Nix-on-Droid configuration:

# droid/default.nix
{ pkgs, ... }: {
  # User configuration
  core.user = {
    userName = "soriphoono";
    shell = pkgs.fish;
  };
  
  # Additional packages
  environment.packages = with pkgs; [
    git
    neovim
    tmux
  ];
}

# homes/soriphoono@droid/default.nix
{ pkgs, ... }: {
  # Droid-specific home configuration
  core = {
    git = {
      userName = "soriphoono";
      userEmail = "soriphoono@gmail.com";
    };
    
    shells = {
      fish.enable = true;
      
      shellAliases = {
        g = "git";
        v = "nvim";
      };
    };
  };
  
  userapps.development = {
    enable = true;
    
    editors.neovim = {
      enable = true;
      settings = import ../nvim { inherit pkgs; };
    };
  };
}

Directory Structure

Recommended structure for Droid configurations:

homes/
├── soriphoono/
│   └── default.nix          # Shared desktop config
├── soriphoono@global/
│   └── default.nix          # Cross-platform config
└── soriphoono@droid/
    └── default.nix          # Droid-specific config

droid/
└── default.nix              # Droid system configuration

The @global and @droid suffixes create isolated configuration contexts:

@global - Applied to all platforms (desktop, servers, mobile)
@droid - Only applied to Nix-on-Droid installations
Base name - Typically used for primary desktop configuration

Best Practices

Resource Management

Mobile devices have limited resources:

# Limit concurrent builds
nix.settings.max-jobs = 1;
nix.settings.cores = 2;

# Use binary caches aggressively
nix.settings.builders-use-substitutes = true;

Lightweight Configurations

Prefer CLI tools over GUI applications:

userapps.development.editors.neovim.enable = true;  # CLI editor
# Avoid: userapps.development.editors.vscode.enable = true;  # GUI editor

Separate Concerns

Use the @droid suffix for mobile-specific configurations:

# homes/user@droid/default.nix
{
  # Mobile-optimized Git settings
  core.git.projectsDir = "/storage/emulated/0/Projects";
}

Test Incrementally

Nix-on-Droid builds can be slow. Test modules incrementally:

nix-on-droid switch --flake .#droid

Troubleshooting

Build Failures

Out of Memory (OOM) If builds fail with OOM errors:

nix.settings.cores = 1;  # Reduce to 1 core
nix.settings.max-jobs = 1;

Missing Substitutes If packages aren’t available in binary caches:

# Add more caches or build locally
nix.settings.substituters = [
  "https://cache.nixos.org"
  "https://nix-community.cachix.org"
];

Module Import Errors

Path Not Found Verify the home configuration paths exist:

ls homes/username/default.nix
ls homes/username@droid/default.nix

Incompatible Options Some NixOS options don’t work on Droid. Check the module’s platform compatibility.

NixOS Modules

Home Manager Modules

Nix-on-Droid Modules

Overview

Module Structure

User Management

Options

Home Manager Integration

Shell Integration

Example Configuration

Nix Configuration

Installed Packages

Nix Settings

Experimental Features

Flake Registry

Resource Limits

Trusted Users

Binary Caches

Flake Registry and Nix Path

Home Module Compatibility

Compatible Modules

Incompatible Features

Droid-Specific Adaptations

Complete Example

Directory Structure

Best Practices

Resource Management

Lightweight Configurations

Separate Concerns

Test Incrementally

Troubleshooting

Build Failures

Module Import Errors

Build docs developers (and LLMs) love

NixOS Modules

Home Manager Modules

Nix-on-Droid Modules

Documentation Index

​Overview

​Module Structure

​User Management

​Options

​Home Manager Integration

​Shell Integration

​Example Configuration

​Nix Configuration

​Installed Packages

​Nix Settings

​Experimental Features

​Flake Registry

​Resource Limits

​Trusted Users

​Binary Caches

​Flake Registry and Nix Path

​Home Module Compatibility

​Compatible Modules

​Incompatible Features

​Droid-Specific Adaptations

​Complete Example

​Directory Structure

​Best Practices

​Resource Management

​Lightweight Configurations

​Separate Concerns

​Test Incrementally

​Troubleshooting

​Build Failures

​Module Import Errors

​Related Resources

Build docs developers (and LLMs) love

Overview

Module Structure

User Management

Options

Home Manager Integration

Shell Integration

Example Configuration

Nix Configuration

Installed Packages

Nix Settings

Experimental Features

Flake Registry

Resource Limits

Trusted Users

Binary Caches

Flake Registry and Nix Path

Home Module Compatibility

Compatible Modules

Incompatible Features

Droid-Specific Adaptations

Complete Example

Directory Structure

Best Practices

Resource Management

Lightweight Configurations

Separate Concerns

Test Incrementally

Troubleshooting

Build Failures

Module Import Errors

Related Resources