nixpkgs/docs/guides/using-modules.md

Using Modules Guide

How to use NixOS and Home Manager modules from m3ta-nixpkgs.

Overview

Modules in m3ta-nixpkgs provide reusable configuration for NixOS (system-level) and Home Manager (user-level) settings. All modules use the m3ta.* namespace.

Module Organization

NixOS Modules

Located in modules/nixos/:

modules/nixos/
├── default.nix    # Aggregates all NixOS modules
├── ports.nix      # Port management
└── mem0.nix      # Mem0 REST API server

Home Manager Modules

Located in modules/home-manager/ with categories:

modules/home-manager/
├── default.nix      # Aggregates all HM modules
├── ports.nix       # Port management
├── cli/            # CLI tools
│   ├── default.nix # Aggregates CLI modules
│   └── zellij-ps.nix
└── coding/         # Development tools
    ├── default.nix # Aggregates coding modules
    └── editors.nix

Importing Modules

NixOS Modules

Import All Modules

{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];
}

Import Specific Module

{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.mem0
  ];
}

Import from Local Path

{config, ...}: {
  imports = [
    ./modules/nixos/mem0.nix
  ];
}

Home Manager Modules

Import All Modules

{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];
}

Import Specific Module

{config, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.ports
  ];
}

Import Category

{config, ...}: {
  imports = [
    # Import all CLI modules
    m3ta-nixpkgs.homeManagerModules.cli.zellij-ps
  ];
}

Available Modules

NixOS Modules

m3ta.ports

Port management across hosts.

m3ta.ports = {
  enable = true;
  definitions = {
    nginx = 80;
    grafana = 3000;
  };
  hostOverrides.laptop = {
    nginx = 8080;
  };
  currentHost = config.networking.hostName;
};

Documentation: Port Management Guide

m3ta.mem0

Mem0 REST API server for AI memory.

m3ta.mem0 = {
  enable = true;
  port = 8000;
  llm = {
    provider = "openai";
    apiKeyFile = "/run/secrets/openai-api-key";
    model = "gpt-4o-mini";
  };
  vectorStore = {
    provider = "qdrant";
    config = {
      host = "localhost";
      port = 6333;
    };
  };
};

Documentation: mem0 Module

Home Manager Modules

m3ta.ports

Port management (similar to NixOS, with generateEnvVars).

m3ta.ports = {
  enable = true;
  definitions = {
    dev-server = 3000;
  };
  generateEnvVars = true;
  currentHost = config.networking.hostName;
};

Documentation: Port Management Guide

cli.zellij-ps

Zellij project switcher for quickly navigating between project folders.

cli.zellij-ps = {
  enable = true;
  package = pkgs.zellij-ps;
};

Documentation: zellij-ps Module

coding.editors

Editor configurations.

m3ta.coding.editors = {
  enable = true;
  neovim.enable = true;
  zed.enable = true;
};

Documentation: Editors Module

Common Patterns

Module Configuration

All modules follow this pattern:

{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "description";
    # ... other options
  };

  config = mkIf cfg.enable {
    # ... configuration
  };
}

Conditional Configuration

Use mkIf to conditionally apply config:

config = mkIf cfg.enable {
  # Only applied when cfg.enable = true
  services.my-service = {
    enable = true;
  };
}

Multiple Conditions

Use mkMerge for multiple conditions:

config = mkMerge [
  (mkIf cfg.feature1.enable {
    # Applied when feature1 is enabled
  })
  (mkIf cfg.feature2.enable {
    # Applied when feature2 is enabled
  })
];

Optional Dependencies

options.m3ta.myModule = {
  enable = mkEnableOption "my module";
  package = mkOption {
    type = types.package;
    default = pkgs.defaultPackage;
  };
};

config = mkIf cfg.enable {
  services.my-service = {
    package = cfg.package;
  };
};

Configuration Examples

Minimal NixOS Configuration

{pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  m3ta.ports = {
    enable = true;
    definitions = {
      my-service = 8080;
    };
    currentHost = "laptop";
  };

  services.my-custom-service = {
    enable = true;
    port = config.m3ta.ports.get "my-service";
  };
}

Full NixOS Configuration

{config, pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  # Port management
  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
      prometheus = 9090;
      mem0 = 8000;
    };
    hostOverrides.laptop = {
      nginx = 8080;
      mem0 = 8081;
    };
    currentHost = config.networking.hostName;
  };

  # Mem0 service
  m3ta.mem0 = {
    enable = true;
    port = config.m3ta.ports.get "mem0";
    llm = {
      provider = "openai";
      apiKeyFile = "/run/secrets/openai-api-key";
    };
    vectorStore = {
      provider = "qdrant";
      config = {
        host = "localhost";
        port = 6333;
      };
    };
  };

  # Nginx
  services.nginx = {
    enable = true;
    httpConfig = ''
      server {
        listen ${toString (config.m3ta.ports.get "nginx")};
        root /var/www;
      }
    '';
  };

  # Grafana
  services.grafana = {
    enable = true;
    settings.server.http_port = config.m3ta.ports.get "grafana";
  };
}

Minimal Home Manager Configuration

{pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];

  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
    };
    currentHost = "desktop";
  };

  home.sessionVariables = {
    DEV_PORT = toString (config.m3ta.ports.get "dev-server");
  };
}

Full Home Manager Configuration

{config, pkgs, ...}: {
  imports = [
    m3ta-nixpkgs.homeManagerModules.default
  ];

  # Port management
  m3ta.ports = {
    enable = true;
    definitions = {
      dev-server = 3000;
      nextjs = 3001;
      vite = 5173;
    };
    hostOverrides.laptop = {
      vite = 5174;
    };
    currentHost = config.networking.hostName;
  };

  # CLI tools
  cli.zellij-ps = {
    enable = true;
  };

  # Coding tools
  coding.editors = {
    enable = true;
    neovim.enable = true;
  };

  # Packages
  home.packages = with pkgs; [
    code2prompt
    zellij-ps
  ];

  # Environment variables
  home.sessionVariables = {
    EDITOR = "nvim";
    DEV_SERVER_PORT = toString (config.m3ta.ports.get "dev-server");
  };
}

Module Options Reference

Standard Options

All modules typically include:

Option	Type	Description
enable	boolean	Enable the module
package	package	Custom package to use
extraConfig	attrs	Additional configuration

Port Management Options

Option	Type	Description
definitions	attrsOf int	Default port definitions
hostOverrides	attrsOf attrs	Host-specific overrides
currentHost	string	Current hostname
generateEnvVars	boolean	Generate environment variables (HM only)

Combining with Other Flakes

Using Multiple Module Sources

{config, ...}: {
  imports = [
    # m3ta-nixpkgs modules
    m3ta-nixpkgs.nixosModules.default

    # Other flake modules
    inputs.impermanence.nixosModules.impermanence
    inputs.sops-nix.nixosModules.sops
  ];

  # Configure all modules
  m3ta.ports = {
    enable = true;
    definitions = {nginx = 80;};
    currentHost = config.networking.hostName;
  };

  environment.persistence = {
    "/persist" = {
      directories = ["/var/lib/mem0"];
    };
  };
}

Using with Secrets

{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
    inputs.sops-nix.nixosModules.sops
  ];

  sops.secrets = {
    openai-api-key = {};
  };

  m3ta.mem0 = {
    enable = true;
    llm = {
      apiKeyFile = config.sops.secrets.openai-api-key.path;
    };
  };
}

Troubleshooting

Module Not Found

Error: error: The option 'm3ta.mymodule' does not exist

Solutions:

1. Make sure you imported the module:

imports = [
  m3ta-nixpkgs.nixosModules.default
];

2. Check module name is correct

# Correct
m3ta.mem0.enable = true;

# Wrong
m3ta.mymodule.enable = true;  # Doesn't exist

Option Type Mismatch

Error: type mismatch at 'm3ta.mymodule.enable', expected a boolean but got a list

Solution: Check option types in documentation

# Correct
m3ta.mymodule.enable = true;

# Wrong
m3ta.mymodule.enable = [true];  # Should be boolean

Port Not Defined

Error: Service "foo" not defined

Solution: Add to port definitions

m3ta.ports = {
  definitions = {
    foo = 8080;  # Add this
  };
};

Best Practices

Use Namespaces

Always use the m3ta.* namespace:

# Good
m3ta.mem0.enable = true;

# Bad (potential conflicts)
mem0.enable = true;

Document Your Configuration

Add comments explaining module usage:

# Port management for multi-host setup
m3ta.ports = {
  enable = true;
  definitions = {
    nginx = 80;
    grafana = 3000;
  };
  hostOverrides.laptop = {
    nginx = 8080;  # Use different port on laptop
  };
  currentHost = config.networking.hostName;
};

# Mem0 AI memory service
m3ta.mem0 = {
  enable = true;
  port = config.m3ta.ports.get "mem0";
};

Test Configuration

# Test NixOS configuration without applying
sudo nixos-rebuild test --flake .#hostname

# Check configuration
nix flake check

# Show all options
nix eval .#nixosConfigurations.hostname.config.m3ta --apply builtins.attrNames

Next Steps

• Port Management - Detailed port management guide
• Adding Packages - How to add new packages
• Architecture - Understanding module structure
• Contributing - Code style and guidelines