docs: update zellij-ps to reflect project switcher functionality
- Update package description and fix mainProgram typo - Rewrite documentation to describe project switching, not process viewing - Add PROJECT_FOLDERS configuration and usage examples - Update all references across docs (README, guides, module overviews)
This commit is contained in:
m3tm3re
316
docs/QUICKSTART.md
Normal file
316
docs/QUICKSTART.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user