m3tam3re/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modules for ports

Browse Source
This commit is contained in:
m3tam3re
2025-10-05 09:44:40 +02:00
parent 56295f694d
commit 62a85af9bc
5 changed files with 316 additions and 291 deletions
Download Patch File Download Diff File Expand all files Collapse all files

397
QUICKSTART.md
View File

@@ -1,45 +1,10 @@
# Quick Start Guide
# Quick Start Guide - Port Management Module
Get started with m3ta-nixpkgs in 5 minutes! This guide covers the most common use cases.
Get started with centralized port management in 5 minutes!
## Prerequisites
## Installation
Ensure Nix flakes are enabled:
```bash
# Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf
mkdir -p ~/.config/nix
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
```
## Quick Usage
### 1. Try a Package Without Installing
```bash
# Run a package directly
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt
# Try it in a temporary shell
nix shell git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
```
### 2. Install to Your Profile
```bash
# Install a package
nix profile install git+https://code.m3ta.dev/m3tam3re/nixpkgs#msty-studio
# List installed packages
nix profile list
# Remove a package
nix profile remove <index>
```
### 3. Add to Your NixOS Configuration
Edit your `flake.nix`:
### Step 1: Add to your flake inputs
```nix
{
@@ -47,244 +12,216 @@ Edit your `flake.nix`:
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
};
}
```
outputs = {nixpkgs, m3ta-nixpkgs, ...}: {
nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
modules = [
{
nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];
### Step 2: Choose your configuration type
environment.systemPackages = with pkgs; [
code2prompt
hyprpaper-random
zellij-ps
];
}
];
## For NixOS Systems
### Basic Setup
```nix
{
imports = [ inputs.m3ta-nixpkgs.nixosModules.default ];
m3ta.ports = {
enable = true;
definitions = {
nginx = 80;
ssh = 22;
grafana = 3000;
};
hostOverrides = {
laptop = { nginx = 8080; ssh = 2222; };
server = {}; # Uses defaults
};
};
}
```
Then rebuild:
### Using Ports
```bash
sudo nixos-rebuild switch --flake .#yourhostname
```nix
# In any NixOS service configuration:
services.nginx.defaultHTTPListenPort = config.m3ta.ports.get "nginx";
services.openssh.ports = [ (config.m3ta.ports.get "ssh") ];
# Firewall rules:
networking.firewall.allowedTCPPorts = [
(config.m3ta.ports.get "ssh")
(config.m3ta.ports.get "nginx")
];
```
### 4. Add to Home Manager (Standalone)
## For Home Manager
Edit your Home Manager `flake.nix`:
### Basic Setup
```nix
{
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";
imports = [ inputs.m3ta-nixpkgs.homeManagerModules.default ];
m3ta.ports = {
enable = true;
definitions = {
vite-dev = 5173;
jupyter = 8888;
local-api = 8000;
};
outputs = {nixpkgs, home-manager, m3ta-nixpkgs, ...}: {
homeConfigurations.m3tam3re = home-manager.lib.homeManagerConfiguration {
pkgs = import nixpkgs {
system = "x86_64-linux";
overlays = [m3ta-nixpkgs.overlays.default];
hostOverrides = {
laptop = { vite-dev = 5174; };
desktop = { jupyter = 9999; };
};
modules = [
{
home.packages = with pkgs; [
code2prompt
pomodoro-timer
];
}
];
};
currentHost = "laptop"; # Set your hostname
generateEnvVars = true; # Creates PORT_* environment variables
};
}
```
Then activate:
```bash
home-manager switch --flake .#m3tam3re
```
### 5. Use During Development (Local Path)
When working on your system configuration:
### Using Ports
```nix
{
inputs = {
# Use local path during development
m3ta-nixpkgs.url = "path:/home/you/projects/m3ta-nixpkgs";
# Or use git+file for uncommitted changes
# m3ta-nixpkgs.url = "git+file:///home/you/projects/m3ta-nixpkgs";
};
}
# Shell aliases:
programs.bash.shellAliases = {
dev = "PORT=${toString (config.m3ta.ports.get "vite-dev")} npm run dev";
};
# Environment variables:
home.sessionVariables = {
DEV_URL = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
};
# Config files:
home.file.".config/myapp/config.json".text = builtins.toJSON {
port = config.m3ta.ports.get "vite-dev";
};
```
### 6. Use Library Functions
## Common Patterns
The repository includes helper functions for common configuration tasks.
#### Port Management Example
### Multi-Host Configuration
```nix
# shared-ports.nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
};
outputs = {nixpkgs, m3ta-nixpkgs, ...}: {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
specialArgs = {inherit inputs; system = "x86_64-linux";};
modules = [
({inputs, system, config, ...}: let
# Import the library
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
# Define all your ports centrally
myPorts = {
ports = {
nginx = 80;
ssh = 22;
grafana = 3000;
prometheus = 9090;
};
hostPorts = {
laptop = {nginx = 8080;}; # Override on laptop
};
};
# Create port helpers
ports = m3taLib.ports.mkPortHelpers myPorts;
hostname = config.networking.hostName;
in {
# Use in configuration
services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
})
];
};
hostOverrides = {
laptop = { nginx = 8080; ssh = 2222; };
server = {};
};
}
```
See `examples/ports-example.nix` for more examples and `lib/README.md` for full documentation.
## Available Packages
| Package | Description | Command |
| ------------------ | ------------------------------- | ---------------------------- |
| `code2prompt` | Convert code to LLM prompts | `nix run .#code2prompt` |
| `hyprpaper-random` | Random wallpaper for Hyprpaper | `nix run .#hyprpaper-random` |
| `launch-webapp` | Launch web applications | `nix run .#launch-webapp` |
| `msty-studio` | Msty Studio application | `nix run .#msty-studio` |
| `pomodoro-timer` | Pomodoro timer utility | `nix run .#pomodoro-timer` |
| `tuxedo-backlight` | Tuxedo laptop backlight control | `nix run .#tuxedo-backlight` |
| `zellij-ps` | Process viewer for Zellij | `nix run .#zellij-ps` |
## Common Commands
```bash
# Show all available packages
nix flake show git+https://code.m3ta.dev/m3tam3re/nixpkgs
# Update the flake lock file
nix flake update
# Build a specific package
nix build git+https://code.m3ta.dev/m3tam3re/nixpkgs#code2prompt
# Check flake validity
nix flake check git+https://code.m3ta.dev/m3tam3re/nixpkgs
```
## Development Workflow
### Adding Your Own Package
1. **Clone the repo:**
```bash
git clone https://code.m3ta.dev/m3tam3re/nixpkgs
cd m3ta-nixpkgs
```
2. **Create package directory:**
```bash
mkdir pkgs/my-package
cp templates/package/default.nix pkgs/my-package/
```
3. **Edit `pkgs/my-package/default.nix`** with your package details
4. **Register in `pkgs/default.nix`:**
```nix
{pkgs, ...}: {
# ... existing packages ...
my-package = pkgs.callPackage ./my-package {};
```nix
# In your flake.nix
let
sharedPorts = import ./shared-ports.nix;
in {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
modules = [
m3ta-nixpkgs.nixosModules.default
{
m3ta.ports = {
enable = true;
definitions = sharedPorts.ports;
hostOverrides = sharedPorts.hostOverrides;
currentHost = "laptop";
};
}
```
5. **Test it:**
```bash
git add -A # Nix flakes require git tracking
nix build .#my-package
```
6. **Commit and push:**
```bash
git commit -m "feat: add my-package"
git push
```
## Troubleshooting
### Issue: "experimental-features" error
**Solution:** Enable flakes in nix.conf (see Prerequisites)
### Issue: "path is not tracked by Git"
**Solution:** `git add` your files before running Nix commands
### Issue: Package fails to build
**Solution:**
```bash
# Check build logs
nix build .#package-name --show-trace
# Try with fresh build
nix build .#package-name --rebuild
];
};
}
```
### Issue: Hash mismatch
### Proxy Configuration
**Solution:** Use `lib.fakeHash` first, then replace with the correct hash from the error message
```nix
services.nginx.virtualHosts."example.com" = {
locations."/grafana/" = {
proxyPass = "http://127.0.0.1:${toString (config.m3ta.ports.get "grafana")}";
};
locations."/prometheus/" = {
proxyPass = "http://127.0.0.1:${toString (config.m3ta.ports.get "prometheus")}";
};
};
```
### Container Services
```nix
virtualisation.oci-containers.containers.grafana = {
image = "grafana/grafana:latest";
ports = [
"${toString (config.m3ta.ports.get "grafana")}:3000"
];
};
```
## Available Functions
| Function | Description | Example |
| ----------------------------------------------- | -------------------------- | ----------------------------------------------- |
| `config.m3ta.ports.get "service"` | Get port for current host | `config.m3ta.ports.get "nginx"` |
| `config.m3ta.ports.getForHost "host" "service"` | Get port for specific host | `config.m3ta.ports.getForHost "laptop" "nginx"` |
| `config.m3ta.ports.all` | All ports (merged) | `config.m3ta.ports.all` |
| `config.m3ta.ports.services` | List service names | `config.m3ta.ports.services` |
## Debugging
### View all configured ports
```bash
# NixOS
cat /etc/m3ta/ports.json | jq
# Home Manager
cat ~/.config/m3ta/ports.json | jq
```
### Check what port is being used
```nix
# Add to your config temporarily
environment.etc."debug-ports.txt".text = ''
nginx: ${toString (config.m3ta.ports.get "nginx")}
ssh: ${toString (config.m3ta.ports.get "ssh")}
all: ${builtins.toJSON config.m3ta.ports.all}
'';
```
## Next Steps
- 📖 Read the full [README.md](README.md) for detailed documentation
- 🤝 Check [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines
- 💡 Browse [examples/](examples/) for more configuration examples
- 🔍 Explore the [templates/](templates/) for creating new packages and modules
- See [examples/ports/README.md](examples/ports/README.md) for comprehensive documentation
- Check [examples/ports/nixos-example.nix](examples/ports/nixos-example.nix) for a full NixOS example
- Check [examples/ports/home-manager-example.nix](examples/ports/home-manager-example.nix) for a full Home Manager example
- Read [examples/ports/flake-example.nix](examples/ports/flake-example.nix) for multi-host setup
## Getting Help
## Common Issues
- 💬 [NixOS Discourse](https://discourse.nixos.org/)
- 💭 [NixOS Matrix Chat](https://matrix.to/#/#nix:nixos.org)
- 📚 [Nix Pills](https://nixos.org/guides/nix-pills/)
- 📖 [Nixpkgs Manual](https://nixos.org/manual/nixpkgs/stable/)
**"Service not defined" error**
---
- Make sure the service is in your `definitions` block
**Ready to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md) to get started!
**Wrong port being used**
- Check your `currentHost` matches your actual hostname
- Verify overrides in `/etc/m3ta/ports.json` or `~/.config/m3ta/ports.json`
**Type errors**
- Ports must be integers: `nginx = 80;` not `nginx = "80";`
## Need Help?
Open an issue at: https://code.m3ta.dev/m3tam3re/nixpkgs

184
README.md
View File

@@ -32,15 +32,21 @@ m3ta-nixpkgs/
│ └── n8n.nix
├── modules/
│ ├── nixos/ # NixOS modules
│ │ └── default.nix
│ │ ├── default.nix
│ │ └── ports.nix # Port management module
│ └── home-manager/ # Home Manager modules
│ ├── default.nix
│ ├── ports.nix # Port management module
│ └── zellij-ps.nix
├── lib/ # Library functions
│ ├── default.nix # Library entry point
│ └── ports.nix # Port management utilities
├── examples/ # Usage examples
│ └── ports-example.nix
│ └── ports/ # Port management examples
│ ├── README.md
│ ├── nixos-example.nix
│ ├── home-manager-example.nix
│ └── flake-example.nix
└── templates/ # Templates for new packages/modules
```
@@ -126,9 +132,18 @@ Add this repository to your flake inputs:
{
imports = [
inputs.m3ta-nixpkgs.nixosModules.default
# Or specific modules:
# inputs.m3ta-nixpkgs.nixosModules.ports
];
# Your custom module options will be available here
# Configure the ports module (if enabled)
m3ta.ports = {
enable = true;
definitions = {
nginx = 80;
ssh = 22;
};
};
}
```
@@ -239,56 +254,134 @@ homeManagerModules = {
};
```
### Using Library Functions
## Port Management Module
The repository includes helper functions to simplify common configuration tasks.
**NEW!** Centrally manage service ports across your NixOS systems and Home Manager configurations with automatic host-specific overrides.
#### Port Management
### Features
Centrally manage service ports across multiple hosts with automatic host-specific overrides:
- ✅ **Centralized Configuration**: Define all ports in one place
- ✅ **Host-Specific Overrides**: Different ports for different machines (laptop, server, desktop)
- ✅ **Type Safety**: Full NixOS/Home Manager type system integration
- ✅ **Auto-Generated Files**: JSON exports and environment variables
- ✅ **Easy Integration**: Works with any service configuration
- ✅ **Conflict Prevention**: Avoid port conflicts across different hosts
### Quick Start - NixOS Module
```nix
# In your flake.nix or configuration
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
};
imports = [ inputs.m3ta-nixpkgs.nixosModules.default ];
outputs = { self, nixpkgs, m3ta-nixpkgs, ... }: {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
specialArgs = { inherit inputs; system = "x86_64-linux"; };
modules = [
({ inputs, system, config, ... }: let
# Import the library
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
m3ta.ports = {
enable = true;
# Define all ports in one place
myPorts = {
ports = {
definitions = {
nginx = 80;
grafana = 3000;
ssh = 22;
prometheus = 9090;
};
hostPorts = {
hostOverrides = {
laptop = {
nginx = 8080; # Non-privileged port on laptop
};
nginx = 8080; # Use non-privileged port
ssh = 2222;
};
};
# Create helper functions
ports = m3taLib.ports.mkPortHelpers myPorts;
# Automatically uses system hostname
currentHost = config.networking.hostName;
};
# Use ports in your configuration
services.nginx.defaultHTTPListenPort = config.m3ta.ports.get "nginx";
services.openssh.ports = [ (config.m3ta.ports.get "ssh") ];
# Firewall with dynamic ports
networking.firewall.allowedTCPPorts = [
(config.m3ta.ports.get "ssh")
(config.m3ta.ports.get "nginx")
];
}
```
### Quick Start - Home Manager Module
```nix
{
imports = [ inputs.m3ta-nixpkgs.homeManagerModules.default ];
m3ta.ports = {
enable = true;
definitions = {
vite-dev = 5173;
jupyter = 8888;
local-api = 8000;
};
hostOverrides = {
laptop = {
vite-dev = 5174;
jupyter = 9999;
};
};
currentHost = "laptop";
# Auto-generate PORT_* environment variables
generateEnvVars = true;
};
# Use ports in your configuration
programs.bash.shellAliases = {
dev = "PORT=${toString (config.m3ta.ports.get "vite-dev")} npm run dev";
jupyter = "jupyter lab --port=${toString (config.m3ta.ports.get "jupyter")}";
};
home.sessionVariables = {
DEV_SERVER = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
};
}
```
### Available Module Functions
- `config.m3ta.ports.get "service"` - Get port for service on current host
- `config.m3ta.ports.getForHost "host" "service"` - Get port for specific host
- `config.m3ta.ports.all` - All ports for current host (merged defaults + overrides)
- `config.m3ta.ports.allForHost "host"` - All ports for specific host
- `config.m3ta.ports.services` - List all defined service names
### Auto-Generated Files
**NixOS**: `/etc/m3ta/ports.json`
**Home Manager**: `~/.config/m3ta/ports.json`
These files contain all port configuration for easy inspection and external tool integration.
### Using the Library Directly
For advanced use cases, you can use the underlying library functions without the module:
```nix
{
outputs = { nixpkgs, m3ta-nixpkgs, ... }: {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
modules = [
({ inputs, system, config, ... }: let
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
myPorts = {
ports = { nginx = 80; grafana = 3000; };
hostPorts = { laptop = { nginx = 8080; }; };
};
portHelpers = m3taLib.ports.mkPortHelpers myPorts;
hostname = config.networking.hostName;
in {
# Use in your configuration
services.nginx.defaultHTTPListenPort = ports.getPort "nginx" hostname;
services.grafana.settings.server.http_port = ports.getPort "grafana" hostname;
# Get all ports for current host
environment.etc."service-ports.json".text =
builtins.toJSON (ports.getHostPorts hostname);
services.nginx.port = portHelpers.getPort "nginx" hostname;
})
];
};
@@ -296,22 +389,15 @@ Centrally manage service ports across multiple hosts with automatic host-specifi
}
```
**Benefits:**
### Documentation
- Single source of truth for all port assignments
- Automatic host-specific overrides (laptop, server, VM, etc.)
- Works across both NixOS and Home Manager configurations
- Easy to see and manage all ports in one place
See comprehensive examples and documentation:
**Available Functions:**
- `mkPortHelpers`: Create port helper functions from a configuration
- `getPort`: Get port for a service with optional host override
- `getHostPorts`: Get all ports for a specific host (merged defaults + overrides)
- `getDefaultPort`: Get default port without host override
- `listServices`: List all defined service names
See `examples/ports-example.nix` for comprehensive usage examples.
- `examples/ports/README.md` - Complete guide with all features
- `examples/ports/nixos-example.nix` - Full NixOS configuration example
- `examples/ports/home-manager-example.nix` - Full Home Manager configuration example
- `examples/ports/flake-example.nix` - Complete multi-host flake setup
- `lib/ports.nix` - Library source code with inline documentation
## Available Packages

6
flake.nix
View File

@@ -56,15 +56,15 @@
# NixOS modules - for system-level configuration
nixosModules = {
default = ./modules/nixos;
# Add individual modules here as needed
# example: myModule = ./modules/nixos/my-module.nix;
# Individual modules for selective imports
ports = ./modules/nixos/ports.nix;
};
# Home Manager modules - for user-level configuration
homeManagerModules = {
default = import ./modules/home-manager;
ports = import ./modules/home-manager/ports.nix;
zellij-ps = import ./modules/home-manager/zellij-ps.nix;
# Add more individual modules as you create them
};
# Library functions - helper utilities for your configuration

1
modules/home-manager/default.nix
View File

@@ -3,5 +3,6 @@
imports = [
./cli
./coding
./ports.nix
];
}

1
modules/nixos/default.nix
View File

@@ -11,6 +11,7 @@
# Add your custom modules here as imports or inline definitions
imports = [
./ports.nix
# Example: ./my-service.nix
# Add more module files here as you create them
];