nixpkgs/docs/guides/getting-started.md

# Getting Started Guide

Initial setup and basic usage of m3ta-nixpkgs.

## Installation

### Prerequisites

Make sure you have Nix installed with flakes enabled:

```bash
# Check Nix version (need 2.4+)
nix --version

# Enable flakes (in /etc/nixos/configuration.nix)
nix.settings.experimental-features = ["nix-command" "flakes"]

# Rebuild NixOS
sudo nixos-rebuild switch
```

### Adding to Your Flake

#### Option 1: NixOS Configuration

Add to your `flake.nix`:

```nix
{
  description = "My NixOS configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    m3ta-nixpkgs = {
      url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    home-manager,
    m3ta-nixpkgs,
    ...
  }: {
    nixosConfigurations = {
      myhost = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./hardware-configuration.nix

          # Import m3ta-nixpkgs modules
          m3ta-nixpkgs.nixosModules.default

          # Apply overlay
          ({pkgs, ...}: {
            nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];

            # Packages from m3ta-nixpkgs are now available
            environment.systemPackages = with pkgs; [
              code2prompt
              zellij-ps
            ];
          })

          # Home Manager integration
          home-manager.nixosModules.home-manager
          {
            home-manager.useGlobalPkgs = true;
            home-manager.useUserPackages = true;
            home-manager.users.myusername = {
              imports = [m3ta-nixpkgs.homeManagerModules.default];
              home.packages = with pkgs; [
                launch-webapp
              ];
            };
          }
        ];
      };
    };
  };
}
```

#### Option 2: Standalone Home Manager

```nix
{
  description = "My Home Manager configuration";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";

    m3ta-nixpkgs = {
      url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = {
    self,
    nixpkgs,
    home-manager,
    m3ta-nixpkgs,
  }: let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [m3ta-nixpkgs.overlays.default];
    };
  in {
    homeConfigurations.myusername = home-manager.lib.homeManagerConfiguration {
      inherit pkgs;
      modules = [
        m3ta-nixpkgs.homeManagerModules.default
        {
          home.username = "myusername";
          home.homeDirectory = "/home/myusername";
          home.packages = with pkgs; [
            code2prompt
            zellij-ps
          ];
          programs.home-manager.enable = true;
        }
      ];
    };
  };
}
```

## Quick Usage

### Using Packages Directly

Without adding to your configuration:

```bash
# Build a package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt

# Run a package
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps

# List all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs
```

### Using Packages in Configuration

After applying overlay:

```nix
# System-wide (NixOS)
environment.systemPackages = with pkgs; [
  code2prompt
  zellij-ps
];

# User-only (Home Manager)
home.packages = with pkgs; [
  launch-webapp
];
```

### Using Modules

```nix
# Import all modules
imports = [
  m3ta-nixpkgs.nixosModules.default
];

# Or import specific module
imports = [
  m3ta-nixpkgs.nixosModules.mem0
];

# Configure module
m3ta.mem0 = {
  enable = true;
  port = 8000;
};
```

## Common Tasks

### Install a Package System-Wide

```nix
# /etc/nixos/configuration.nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    code2prompt
    hyprpaper-random
  ];
}

# Apply
sudo nixos-rebuild switch
```

### Install a Package for Your User

```nix
# home.nix
{pkgs, ...}: {
  home.packages = with pkgs; [
    launch-webapp
    zellij-ps
  ];
}

# Apply
home-manager switch
```

### Enable a NixOS Module

```nix
# /etc/nixos/configuration.nix
{config, ...}: {
  imports = [
    m3ta-nixpkgs.nixosModules.default
  ];

  m3ta.mem0 = {
    enable = true;
    port = 8000;
  };

  # Apply
  # sudo nixos-rebuild switch
}
```

### Enable a Home Manager Module

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

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

  # Apply
  # home-manager switch
}
```

### Use Port Management

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

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

## Available Packages

| Package            | Description                           |
| ------------------ | ------------------------------------- |
| `code2prompt`      | Convert code to prompts               |
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
| `launch-webapp`    | Launch web applications               |
| `mem0`             | AI memory assistant with vector storage |
| `msty-studio`      | Msty Studio application               |
| `pomodoro-timer`   | Pomodoro timer utility                |
| `tuxedo-backlight` | Backlight control for Tuxedo laptops  |
| `zellij-ps`        | Project switcher for Zellij           |

## Available Modules

### NixOS Modules

- `ports` - Port management across hosts
- `mem0` - Mem0 REST API server

### Home Manager Modules

- `ports` - Port management (with `generateEnvVars`)
- `cli.zellij-ps` - Zellij project switcher
- `coding.editors` - Editor configurations

## Development

### Development Shells

```bash
# Default dev shell
nix develop

# Python dev shell
nix develop .#python

# DevOps dev shell
nix develop .#devops
```

### Building and Testing

```bash
# Build package
nix build .#code2prompt

# Validate flake
nix flake check

# List outputs
nix flake show

# Format code
nix fmt
```

### Linting (in dev shell)

```bash
nix develop

# Run linter
statix check .

# Find dead code
deadnix .
```

## Troubleshooting

### Package Not Found

**Error**: `error: undefined variable 'code2prompt'`

**Solution**: Make sure you applied the overlay:

```nix
nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];
```

### Module Not Found

**Error**: `error: The option 'm3ta.mem0' does not exist`

**Solution**: Make sure you imported the module:

```nix
imports = [
  m3ta-nixpkgs.nixosModules.default
  # or
  m3ta-nixpkgs.nixosModules.mem0
];
```

### Hash Mismatch

**Error**: `got: sha256-AAAAAAAA... expected: sha256-BBBBBB...`

**Solution**: Copy the `got` hash from the error and update the package definition.

### Building for Different System

```bash
# Build for aarch64-linux
nix build .#code2prompt --system aarch64-linux

# Build for macOS
nix build .#code2prompt --system x86_64-darwin
```

## Next Steps

- [Adding Packages](./adding-packages.md) - How to add new packages
- [Using Modules](./using-modules.md) - Deep dive into modules
- [Port Management](./port-management.md) - Managing service ports
- [Architecture](../ARCHITECTURE.md) - Understanding the repository structure