Nix-on-Droid Modules

Module reference for Nix-on-Droid mobile configurations

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:

1. homes/<username>/default.nix - Primary user configuration
2. homes/<username>@global/default.nix - Global settings across all platforms
3. 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 = "[e-mail]";
    };
    
    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.

---

Related Resources

• Nix-on-Droid GitHub
• Nix-on-Droid Wiki
• Home Manager Manual