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.settings.experimental-features = ["nix-command" "flakes"];

Adding to Your Flake

NixOS Configuration

{
  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

{
  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:

# 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

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

Use a Package for Your User Only

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

Use a NixOS Module

{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

{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

# 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

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

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

Or reference directly:

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

Module Not Found

Make sure you imported the module:

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:

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

Next Steps

• Architecture - Understanding the repository structure
• Adding Packages - How to add new packages
• Using Modules - Deep dive into modules
• Port Management - Managing service ports