modules for ports
This commit is contained in:
m3tam3re
415
QUICKSTART.md
415
QUICKSTART.md
@@ -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:
|
### Step 1: Add to your flake inputs
|
||||||
|
|
||||||
```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`:
|
|
||||||
|
|
||||||
```nix
|
```nix
|
||||||
{
|
{
|
||||||
@@ -47,244 +12,216 @@ Edit your `flake.nix`:
|
|||||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||||
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
|
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
|
||||||
};
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
outputs = {nixpkgs, m3ta-nixpkgs, ...}: {
|
### Step 2: Choose your configuration type
|
||||||
nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
|
|
||||||
modules = [
|
|
||||||
{
|
|
||||||
nixpkgs.overlays = [m3ta-nixpkgs.overlays.default];
|
|
||||||
|
|
||||||
environment.systemPackages = with pkgs; [
|
## For NixOS Systems
|
||||||
code2prompt
|
|
||||||
hyprpaper-random
|
### Basic Setup
|
||||||
zellij-ps
|
|
||||||
];
|
```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
|
```nix
|
||||||
sudo nixos-rebuild switch --flake .#yourhostname
|
# 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
|
```nix
|
||||||
{
|
{
|
||||||
inputs = {
|
imports = [ inputs.m3ta-nixpkgs.homeManagerModules.default ];
|
||||||
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";
|
|
||||||
};
|
|
||||||
|
|
||||||
outputs = {nixpkgs, home-manager, m3ta-nixpkgs, ...}: {
|
m3ta.ports = {
|
||||||
homeConfigurations.m3tam3re = home-manager.lib.homeManagerConfiguration {
|
enable = true;
|
||||||
pkgs = import nixpkgs {
|
|
||||||
system = "x86_64-linux";
|
|
||||||
overlays = [m3ta-nixpkgs.overlays.default];
|
|
||||||
};
|
|
||||||
|
|
||||||
modules = [
|
definitions = {
|
||||||
{
|
vite-dev = 5173;
|
||||||
home.packages = with pkgs; [
|
jupyter = 8888;
|
||||||
code2prompt
|
local-api = 8000;
|
||||||
pomodoro-timer
|
|
||||||
];
|
|
||||||
}
|
|
||||||
];
|
|
||||||
};
|
};
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Then activate:
|
hostOverrides = {
|
||||||
|
laptop = { vite-dev = 5174; };
|
||||||
```bash
|
desktop = { jupyter = 9999; };
|
||||||
home-manager switch --flake .#m3tam3re
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5. Use During Development (Local Path)
|
|
||||||
|
|
||||||
When working on your system configuration:
|
|
||||||
|
|
||||||
```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";
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 6. Use Library Functions
|
|
||||||
|
|
||||||
The repository includes helper functions for common configuration tasks.
|
|
||||||
|
|
||||||
#### Port Management Example
|
|
||||||
|
|
||||||
```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;
|
|
||||||
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;
|
|
||||||
})
|
|
||||||
];
|
|
||||||
};
|
};
|
||||||
|
|
||||||
|
currentHost = "laptop"; # Set your hostname
|
||||||
|
generateEnvVars = true; # Creates PORT_* environment variables
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
See `examples/ports-example.nix` for more examples and `lib/README.md` for full documentation.
|
### Using Ports
|
||||||
|
|
||||||
## Available Packages
|
```nix
|
||||||
|
# Shell aliases:
|
||||||
|
programs.bash.shellAliases = {
|
||||||
|
dev = "PORT=${toString (config.m3ta.ports.get "vite-dev")} npm run dev";
|
||||||
|
};
|
||||||
|
|
||||||
| Package | Description | Command |
|
# Environment variables:
|
||||||
| ------------------ | ------------------------------- | ---------------------------- |
|
home.sessionVariables = {
|
||||||
| `code2prompt` | Convert code to LLM prompts | `nix run .#code2prompt` |
|
DEV_URL = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
|
||||||
| `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
|
# Config files:
|
||||||
|
home.file.".config/myapp/config.json".text = builtins.toJSON {
|
||||||
```bash
|
port = config.m3ta.ports.get "vite-dev";
|
||||||
# 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
|
## Common Patterns
|
||||||
|
|
||||||
### Adding Your Own Package
|
### Multi-Host Configuration
|
||||||
|
|
||||||
1. **Clone the repo:**
|
```nix
|
||||||
|
# shared-ports.nix
|
||||||
|
{
|
||||||
|
ports = {
|
||||||
|
nginx = 80;
|
||||||
|
ssh = 22;
|
||||||
|
grafana = 3000;
|
||||||
|
};
|
||||||
|
|
||||||
```bash
|
hostOverrides = {
|
||||||
git clone https://code.m3ta.dev/m3tam3re/nixpkgs
|
laptop = { nginx = 8080; ssh = 2222; };
|
||||||
cd m3ta-nixpkgs
|
server = {};
|
||||||
```
|
};
|
||||||
|
}
|
||||||
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 {};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
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
|
```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";
|
||||||
|
};
|
||||||
|
}
|
||||||
|
];
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
**Solution:** Use `lib.fakeHash` first, then replace with the correct hash from the error message
|
### Proxy Configuration
|
||||||
|
|
||||||
|
```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
|
## Next Steps
|
||||||
|
|
||||||
- 📖 Read the full [README.md](README.md) for detailed documentation
|
- See [examples/ports/README.md](examples/ports/README.md) for comprehensive documentation
|
||||||
- 🤝 Check [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines
|
- Check [examples/ports/nixos-example.nix](examples/ports/nixos-example.nix) for a full NixOS example
|
||||||
- 💡 Browse [examples/](examples/) for more configuration examples
|
- Check [examples/ports/home-manager-example.nix](examples/ports/home-manager-example.nix) for a full Home Manager example
|
||||||
- 🔍 Explore the [templates/](templates/) for creating new packages and modules
|
- 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/)
|
**"Service not defined" error**
|
||||||
- 💭 [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/)
|
|
||||||
|
|
||||||
---
|
- 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
184
README.md
@@ -32,15 +32,21 @@ m3ta-nixpkgs/
|
|||||||
│ └── n8n.nix
|
│ └── n8n.nix
|
||||||
├── modules/
|
├── modules/
|
||||||
│ ├── nixos/ # NixOS modules
|
│ ├── nixos/ # NixOS modules
|
||||||
│ │ └── default.nix
|
│ │ ├── default.nix
|
||||||
|
│ │ └── ports.nix # Port management module
|
||||||
│ └── home-manager/ # Home Manager modules
|
│ └── home-manager/ # Home Manager modules
|
||||||
│ ├── default.nix
|
│ ├── default.nix
|
||||||
|
│ ├── ports.nix # Port management module
|
||||||
│ └── zellij-ps.nix
|
│ └── zellij-ps.nix
|
||||||
├── lib/ # Library functions
|
├── lib/ # Library functions
|
||||||
│ ├── default.nix # Library entry point
|
│ ├── default.nix # Library entry point
|
||||||
│ └── ports.nix # Port management utilities
|
│ └── ports.nix # Port management utilities
|
||||||
├── examples/ # Usage examples
|
├── 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
|
└── templates/ # Templates for new packages/modules
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -126,9 +132,18 @@ Add this repository to your flake inputs:
|
|||||||
{
|
{
|
||||||
imports = [
|
imports = [
|
||||||
inputs.m3ta-nixpkgs.nixosModules.default
|
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
|
```nix
|
||||||
# In your flake.nix or configuration
|
|
||||||
{
|
{
|
||||||
inputs = {
|
imports = [ inputs.m3ta-nixpkgs.nixosModules.default ];
|
||||||
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
|
||||||
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
|
m3ta.ports = {
|
||||||
|
enable = true;
|
||||||
|
|
||||||
|
definitions = {
|
||||||
|
nginx = 80;
|
||||||
|
grafana = 3000;
|
||||||
|
ssh = 22;
|
||||||
|
prometheus = 9090;
|
||||||
|
};
|
||||||
|
|
||||||
|
hostOverrides = {
|
||||||
|
laptop = {
|
||||||
|
nginx = 8080; # Use non-privileged port
|
||||||
|
ssh = 2222;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
# Automatically uses system hostname
|
||||||
|
currentHost = config.networking.hostName;
|
||||||
};
|
};
|
||||||
|
|
||||||
outputs = { self, nixpkgs, m3ta-nixpkgs, ... }: {
|
# 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 {
|
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
|
||||||
system = "x86_64-linux";
|
|
||||||
specialArgs = { inherit inputs; system = "x86_64-linux"; };
|
|
||||||
modules = [
|
modules = [
|
||||||
({ inputs, system, config, ... }: let
|
({ inputs, system, config, ... }: let
|
||||||
# Import the library
|
|
||||||
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
|
m3taLib = inputs.m3ta-nixpkgs.lib.${system};
|
||||||
|
|
||||||
# Define all ports in one place
|
|
||||||
myPorts = {
|
myPorts = {
|
||||||
ports = {
|
ports = { nginx = 80; grafana = 3000; };
|
||||||
nginx = 80;
|
hostPorts = { laptop = { nginx = 8080; }; };
|
||||||
grafana = 3000;
|
|
||||||
prometheus = 9090;
|
|
||||||
};
|
|
||||||
hostPorts = {
|
|
||||||
laptop = {
|
|
||||||
nginx = 8080; # Non-privileged port on laptop
|
|
||||||
};
|
|
||||||
};
|
|
||||||
};
|
};
|
||||||
|
|
||||||
# Create helper functions
|
portHelpers = m3taLib.ports.mkPortHelpers myPorts;
|
||||||
ports = m3taLib.ports.mkPortHelpers myPorts;
|
|
||||||
hostname = config.networking.hostName;
|
hostname = config.networking.hostName;
|
||||||
in {
|
in {
|
||||||
# Use in your configuration
|
services.nginx.port = portHelpers.getPort "nginx" hostname;
|
||||||
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);
|
|
||||||
})
|
})
|
||||||
];
|
];
|
||||||
};
|
};
|
||||||
@@ -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
|
See comprehensive examples and documentation:
|
||||||
- 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
|
|
||||||
|
|
||||||
**Available Functions:**
|
- `examples/ports/README.md` - Complete guide with all features
|
||||||
|
- `examples/ports/nixos-example.nix` - Full NixOS configuration example
|
||||||
- `mkPortHelpers`: Create port helper functions from a configuration
|
- `examples/ports/home-manager-example.nix` - Full Home Manager configuration example
|
||||||
- `getPort`: Get port for a service with optional host override
|
- `examples/ports/flake-example.nix` - Complete multi-host flake setup
|
||||||
- `getHostPorts`: Get all ports for a specific host (merged defaults + overrides)
|
- `lib/ports.nix` - Library source code with inline documentation
|
||||||
- `getDefaultPort`: Get default port without host override
|
|
||||||
- `listServices`: List all defined service names
|
|
||||||
|
|
||||||
See `examples/ports-example.nix` for comprehensive usage examples.
|
|
||||||
|
|
||||||
## Available Packages
|
## Available Packages
|
||||||
|
|
||||||
|
|||||||
@@ -56,15 +56,15 @@
|
|||||||
# NixOS modules - for system-level configuration
|
# NixOS modules - for system-level configuration
|
||||||
nixosModules = {
|
nixosModules = {
|
||||||
default = ./modules/nixos;
|
default = ./modules/nixos;
|
||||||
# Add individual modules here as needed
|
# Individual modules for selective imports
|
||||||
# example: myModule = ./modules/nixos/my-module.nix;
|
ports = ./modules/nixos/ports.nix;
|
||||||
};
|
};
|
||||||
|
|
||||||
# Home Manager modules - for user-level configuration
|
# Home Manager modules - for user-level configuration
|
||||||
homeManagerModules = {
|
homeManagerModules = {
|
||||||
default = import ./modules/home-manager;
|
default = import ./modules/home-manager;
|
||||||
|
ports = import ./modules/home-manager/ports.nix;
|
||||||
zellij-ps = import ./modules/home-manager/zellij-ps.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
|
# Library functions - helper utilities for your configuration
|
||||||
|
|||||||
@@ -3,5 +3,6 @@
|
|||||||
imports = [
|
imports = [
|
||||||
./cli
|
./cli
|
||||||
./coding
|
./coding
|
||||||
|
./ports.nix
|
||||||
];
|
];
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -11,6 +11,7 @@
|
|||||||
# Add your custom modules here as imports or inline definitions
|
# Add your custom modules here as imports or inline definitions
|
||||||
|
|
||||||
imports = [
|
imports = [
|
||||||
|
./ports.nix
|
||||||
# Example: ./my-service.nix
|
# Example: ./my-service.nix
|
||||||
# Add more module files here as you create them
|
# Add more module files here as you create them
|
||||||
];
|
];
|
||||||
|
|||||||
Reference in New Issue
Block a user