nixpkgs/docs/modules/nixos/overview.md

# NixOS Modules Overview

Overview of available NixOS modules in m3ta-nixpkgs.

## Available Modules

- [ports](./ports.md) - Port management across hosts
- [mem0](./mem0.md) - Mem0 REST API server

## Importing Modules

### Import All Modules

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

### Import Specific Module

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

## Module Namespace

All NixOS modules use the `m3ta.*` namespace:

```nix
# Port management
m3ta.ports = {
  enable = true;
  definitions = {nginx = 80;};
};

# Mem0 service
m3ta.mem0 = {
  enable = true;
  port = 8000;
};
```

## Common Patterns

### Enable Module

All modules follow the pattern:

```nix
m3ta.moduleName = {
  enable = true;
  # ... options
};
```

### Configuration

Modules typically provide these sections:

- `enable` - Enable/disable module
- `package` - Custom package (optional)
- Configuration options specific to module

## Integration Examples

### With Port Management

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

  m3ta.ports = {
    enable = true;
    definitions = {
      nginx = 80;
      grafana = 3000;
      mem0 = 8000;
    };
    currentHost = config.networking.hostName;
  };

  m3ta.mem0 = {
    enable = true;
    port = config.m3ta.ports.get "mem0";
  };

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

### With Home Manager

```nix
{config, ...}: {
  # NixOS modules
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  # Home Manager integration
  home-manager.users.myusername = {
    imports = [
      m3ta-nixpkgs.homeManagerModules.default
    ];

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

## Module Locations

- `modules/nixos/ports.nix` - Port management module
- `modules/nixos/mem0.nix` - Mem0 REST API server module

## Adding New Modules

1. Create module file: `modules/nixos/my-module.nix`
2. Follow standard pattern:

```nix
{ config, lib, pkgs, ... }:
with lib; let
  cfg = config.m3ta.myModule;
in {
  options.m3ta.myModule = {
    enable = mkEnableOption "my module";
  };

  config = mkIf cfg.enable {
    # Configuration
  };
}
```

3. Import in `modules/nixos/default.nix`

## Related

- [Port Management Guide](../guides/port-management.md) - Detailed port management usage
- [Using Modules Guide](../guides/using-modules.md) - How to use modules
- [Home Manager Modules](./home-manager/overview.md) - User-level modules