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:
|
||||
|
||||
```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 ];
|
||||
|
||||
outputs = {nixpkgs, home-manager, m3ta-nixpkgs, ...}: {
|
||||
homeConfigurations.m3tam3re = home-manager.lib.homeManagerConfiguration {
|
||||
pkgs = import nixpkgs {
|
||||
system = "x86_64-linux";
|
||||
overlays = [m3ta-nixpkgs.overlays.default];
|
||||
};
|
||||
m3ta.ports = {
|
||||
enable = true;
|
||||
|
||||
modules = [
|
||||
{
|
||||
home.packages = with pkgs; [
|
||||
code2prompt
|
||||
pomodoro-timer
|
||||
];
|
||||
}
|
||||
];
|
||||
definitions = {
|
||||
vite-dev = 5173;
|
||||
jupyter = 8888;
|
||||
local-api = 8000;
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Then activate:
|
||||
|
||||
```bash
|
||||
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;
|
||||
})
|
||||
];
|
||||
hostOverrides = {
|
||||
laptop = { vite-dev = 5174; };
|
||||
desktop = { jupyter = 9999; };
|
||||
};
|
||||
|
||||
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 |
|
||||
| ------------------ | ------------------------------- | ---------------------------- |
|
||||
| `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` |
|
||||
# Environment variables:
|
||||
home.sessionVariables = {
|
||||
DEV_URL = "http://localhost:${toString (config.m3ta.ports.get "vite-dev")}";
|
||||
};
|
||||
|
||||
## 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
|
||||
# Config files:
|
||||
home.file.".config/myapp/config.json".text = builtins.toJSON {
|
||||
port = config.m3ta.ports.get "vite-dev";
|
||||
};
|
||||
```
|
||||
|
||||
## 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
|
||||
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 {};
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
hostOverrides = {
|
||||
laptop = { nginx = 8080; ssh = 2222; };
|
||||
server = {};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
- 📖 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
|
||||
|
||||
Reference in New Issue
Block a user