nixpkgs/docs/QUICKSTART.md

# Quick Start Guide

Get started with m3ta-nixpkgs in 5 minutes.

## Prerequisites

- Nix with flakes enabled (Nix 2.4+)
- Basic familiarity with NixOS and/or Home Manager

Enable flakes in `/etc/nixos/configuration.nix`:

```nix
nix.settings.experimental-features = ["nix-command" "flakes"];
```

## Adding to Your Flake

### NixOS Configuration

```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 = {
      hostname = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [
          ./hardware-configuration.nix

          # Import m3ta's NixOS modules
          m3ta-nixpkgs.nixosModules.default

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

            environment.systemPackages = with pkgs; [
              code2prompt
              zellij-ps
              # Regular nixpkgs packages
              vim
            ];
          })

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

### 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,
  } @ inputs: let
    system = "x86_64-linux";
    pkgs = import nixpkgs {
      inherit system;
      overlays = [m3ta-nixpkgs.overlays.default];
    };
  in {
    homeConfigurations.yourusername = home-manager.lib.homeManagerConfiguration {
      inherit pkgs;
      extraSpecialArgs = {inherit inputs;};
      modules = [
        m3ta-nixpkgs.homeManagerModules.default
        {
          home.username = "yourusername";
          home.homeDirectory = "/home/yourusername";
          home.packages = with pkgs; [
            code2prompt
            zellij-ps
          ];
          programs.home-manager.enable = true;
        }
      ];
    };
  };
}
```

## Using Packages Without Configuration

You can build and run 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
```

## Common Use Cases

### Use a Package System-Wide

```nix
# In configuration.nix
{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    code2prompt      # From m3ta-nixpkgs
    git             # From nixpkgs
  ];
}
```

### Use a Package for Your User Only

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

### Use a NixOS Module

```nix
{config, ...}: {
  imports = [
    # Or import the default which includes all modules
  ];

  # Enable mem0 service
  m3ta.mem0 = {
    enable = true;
    port = 8000;
    llm = {
      provider = "openai";
      apiKeyFile = "/run/secrets/openai-api-key";
    };
  };
}
```

### Use Port Management

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

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

## 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           |

## Essential Commands

```bash
# Validate your configuration
nix flake check

# Format Nix files
nix fmt

# Apply NixOS configuration
sudo nixos-rebuild switch

# Apply Home Manager configuration
home-manager switch

# Enter development shell
nix develop .#python  # Python shell
nix develop .#devops  # DevOps shell

# List all outputs
nix flake show
```

## Development Workflow

```bash
# Clone repository
git clone https://code.m3ta.dev/m3tam3re/nixpkgs.git
cd nixpkgs

# Create a new package
nix flake init -t .#package

# Test package build
nix build .#your-package

# Run linting (in dev shell)
nix develop
statix check .
deadnix .

# Format before commit
nix fmt
```

## Troubleshooting

### Package Not Found

Make sure you applied the overlay:

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

Or reference directly:

```nix
inputs.m3ta-nixpkgs.packages.${pkgs.system}.package-name
```

### Module Not Found

Make sure you imported the module:

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

### Hash Mismatch

If you're developing and get a hash error, rebuild to get the real hash:

```bash
nix build .#your-package
# Copy hash from error and update package
```

## Next Steps

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