diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 94b6b38..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -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