105 lines
2.7 KiB
Markdown
105 lines
2.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a NixOS VPS configuration using flakes. It deploys a private server with:
|
|
- **SearXNG**: Private meta-search engine with Anubis AI firewall protection
|
|
- **OpenClaw**: AI agent with Discord integration (uses ZAI/GLM models)
|
|
- **Nginx**: Reverse proxy with automatic Let's Encrypt certificates
|
|
|
|
## Commands
|
|
|
|
### Deploy Configuration
|
|
```bash
|
|
# Apply configuration changes to the system
|
|
sudo nixos-rebuild switch --flake .#nixos
|
|
|
|
# Dry-run to check configuration without applying
|
|
nixos-rebuild build --flake .#nixos
|
|
|
|
# Update system with latest nixpkgs
|
|
sudo nixos-rebuild switch --upgrade
|
|
```
|
|
|
|
### Secrets Management
|
|
```bash
|
|
# Generate a new age key for SOPS
|
|
nix-shell -p age --run "age-keygen -o key.txt"
|
|
|
|
# Edit encrypted secrets
|
|
nix-shell -p sops --run "sops secrets/secrets.yaml"
|
|
```
|
|
|
|
### Container Management
|
|
```bash
|
|
# View running containers
|
|
sudo podman ps
|
|
|
|
# View container logs
|
|
sudo podman logs <container-name>
|
|
|
|
# Restart a container service
|
|
sudo systemctl restart podman-<container-name>.service
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Module System
|
|
All services are defined as custom modules under `myModules.` namespace in `modules/`:
|
|
|
|
```
|
|
modules/
|
|
├── default.nix # Imports all modules
|
|
├── system.nix # Base system config, packages
|
|
├── podman.nix # Container runtime setup
|
|
├── nginx.nix # Reverse proxy + ACME
|
|
├── searxng.nix # Search engine stack (SearXNG + Valkey + Anubis)
|
|
└── openclaw-podman.nix # AI agent container
|
|
```
|
|
|
|
### Module Pattern
|
|
Each module follows this structure:
|
|
```nix
|
|
{
|
|
config, lib, pkgs, ...
|
|
}:
|
|
let
|
|
cfg = config.myModules.<module-name>;
|
|
in
|
|
{
|
|
options.myModules.<module-name> = { ... };
|
|
config = lib.mkIf cfg.enable { ... };
|
|
}
|
|
```
|
|
|
|
Modules are enabled/configured in `configuration.nix`:
|
|
```nix
|
|
myModules.searxng = {
|
|
enable = true;
|
|
port = 8888;
|
|
domain = "search.example.com";
|
|
};
|
|
```
|
|
|
|
### Secrets (SOPS)
|
|
- Secrets defined in `secrets/secrets.yaml` (encrypted)
|
|
- SOPS configuration in `.sops.yaml`
|
|
- Secrets are injected into containers via environment files:
|
|
- `sops.templates."service.env"` creates env file with interpolated secrets
|
|
- Container references: `environmentFiles = [ config.sops.templates."service.env".path ]`
|
|
|
|
### Container Networking
|
|
- SearXNG uses a dedicated podman network (`searxng-net`)
|
|
- Services bind to `127.0.0.1` only; Nginx handles external traffic
|
|
- OpenClaw uses `--network=host` for Discord gateway access
|
|
|
|
### Service Dependencies
|
|
Modules declare dependencies explicitly:
|
|
```nix
|
|
config = lib.mkIf cfg.enable {
|
|
myModules.podman.enable = true; # Ensures podman is enabled
|
|
...
|
|
};
|
|
```
|