quckstart for port management
This commit is contained in:
m3tam3re
227
QUICKSTART.md
227
QUICKSTART.md
@@ -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
|
|
||||||
Reference in New Issue
Block a user