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

quckstart for port management

Browse Source
This commit is contained in:
m3tam3re
2025-10-05 12:43:41 +02:00
parent 735c22cf36
commit 8eb3693775
1 changed files with 0 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
QUICKSTART.md
View File

@@ -1,227 +0,0 @@
# Quick Start Guide - Port Management Module
Get started with centralized port management in 5 minutes!
## Installation
### Step 1: Add to your flake inputs
```nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
m3ta-nixpkgs.url = "git+https://code.m3ta.dev/m3tam3re/nixpkgs";
};
}
```
### Step 2: Choose your configuration type
## 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
};
};
}
```
### Using Ports
```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")
];
```
## For Home Manager
### Basic Setup
```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; };
desktop = { jupyter = 9999; };
};
currentHost = "laptop"; # Set your hostname
generateEnvVars = true; # Creates PORT_* environment variables
};
}
```
### Using Ports
```nix
# 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";
};
```
## Common Patterns
### Multi-Host Configuration
```nix
# shared-ports.nix
{
ports = {
nginx = 80;
ssh = 22;
grafana = 3000;
};
hostOverrides = {
laptop = { nginx = 8080; ssh = 2222; };
server = {};
};
}
```
```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";
};
}
];
};
}
```
### 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
- 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
## Common Issues
**"Service not defined" error**
- Make sure the service is in your `definitions` block
**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