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
402
docs/guides/getting-started.md
Normal file
402
docs/guides/getting-started.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# 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
|
||||
];
|
||||
|
||||
m3ta.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
|
||||
Reference in New Issue
Block a user