# tinsnip - Homelab Infrastructure Platform

Provides opinionated container management which standardizes how services are configured, deployed, and managed in homelab environments.

## Overview

tinsnip provides the infrastructure foundation for deploying services with:
- **Standardized UIDs** following the SMEP scheme for proper NFS permissions
- **NFS-backed persistence** for config, data, and state
- **XDG integration** via symbolic links in standard locations
- **Rootless Docker** with consistent host-to-container data mapping
- **Service isolation** through dedicated users and namespaces

## Service Catalog

Services are maintained in a separate repository.

See: [https://tangled.sh/dynamicalsystem.com/service](https://tangled.sh/dynamicalsystem.com/service)

To develop new services, you can create `docker-compose.yml`, `README.md` and `setup.sh` files in a folder under the `./service` folder. This enables a more streamlined workflow and is gitgnored so be sure to migrate to a separate service repo.

## Quick Start

### Install tinsnip
```bash
# Install tinsnip with service catalog
curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | INSTALL_SERVICES=true bash

# Add to PATH
export PATH="$HOME/.local/opt/dynamicalsystem.tinsnip/bin:$PATH"
echo 'export PATH="$HOME/.local/opt/dynamicalsystem.tinsnip/bin:$PATH"' >> ~/.bashrc
```

### Legacy Script Interface (Still Supported)

```bash
# Install with custom service catalog
curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | \
  SERVICE_REPO_URL="git@github.com:mycompany/services" INSTALL_SERVICES=true bash

# Use scripts directly
cd ~/.local/opt/dynamicalsystem.tinsnip
./machine/setup.sh gateway prod DS412plus.local
```

## Architecture

tinsnip uses a multi-environment deployment model with:

- **Service Isolation**: Each service runs under dedicated users (UID 11000+ range)
- **Environment Separation**: Separate prod/test deployments with different UIDs and ports
- **Namespace Support**: Configurable namespaces, called sheets, for multi-tenant deployments (defaults to `sheet`)
- **Rootless Docker**: Complete container isolation without root privileges
- **NFS-Backed Storage**: Persistent data across host rebuilds
- **Automatic Port Allocation**: SMEP-based numbering prevents UID and port conflicts

### UID and Port Convention

Machines follow a 5-digit numbering scheme (`SMEP`) for both UIDs and ports:

| Machine | Environment | UID (P=0) | Port Range | Primary Port | Secondary Port |
|---------|-------------|-----------|------------|--------------|----------------|
| station | prod | 11000 | 11000-11009 | 11000 | 11001 |
| station | test | 11010 | 11010-11019 | 11010 | 11011 |
| lldap | prod | 11200 | 11200-11209 | 11200 | 11201 |
| lldap | test | 11210 | 11210-11219 | 11210 | 11211 |

For details on UID conventions, port allocation, and deployment patterns, see [deployment_strategy.md](docs/deployment_strategy.md). For step-by-step machine setup including NFS configuration, see [create_machine.md](docs/create_machine.md). For sheet configuration options, see [sheet_configuration.md](docs/sheet_configuration.md). For machine registry mechanics and machine number assignment, see [machine_registry.md](docs/machine_registry.md).

## CLI Reference

The `tin` command provides a modern interface for tinsnip operations:

### Core Commands
```bash
tin sheet <name>                  # Create/register sheet
tin machine <service> <env>       # Create service machine environment  
tin service <service-env> <name>  # Deploy service to machine

# Examples
tin sheet infrastructure          # Register infrastructure sheet
tin machine gazette prod          # Create gazette-prod (auto-discover NAS)
tin service gazette-prod lldap    # Deploy lldap to gazette-prod
```

### Management Commands
```bash
tin registry                      # Manage registries (sheets, NAS servers)
tin key                          # Manage SSH keys for NAS access
tin status                       # Show tinsinp status
tin help                         # Show help information
```

### Registry Management
```bash
tin sheet list                           # List registered sheets
tin sheet show <name>                   # Show sheet details
tin registry service list               # List services in current sheet
tin key generate <nas-server>           # Generate SSH key for NAS server
```

## Service Management

### Using CLI Commands
```bash
# Deploy services
tin service gateway-prod lldap         # Deploy LLDAP to gateway-prod
tin status                            # Show all service status
tin service gateway-prod logs lldap   # View service logs

# Registry management
tin registry service list             # List services in current sheet
tin sheet list                        # List all sheets
```

### Legacy Direct Management
```bash
# Switch to service user
sudo -u gateway-prod -i

# Check service status  
cd /mnt/gateway-prod/service/lldap
docker compose ps

# View logs
docker compose logs -f
```

## Integration Guide

### LLDAP Configuration
- **Base DN**: `dc=home,dc=local`
- **Production**: `tinsnip-host:11000` (LDAP), `tinsnip-host:11001` (Web UI)
- **Test**: `tinsnip-host:11010` (LDAP), `tinsnip-host:11011` (Web UI)

### For Ubuntu/Debian Systems
```bash
# Configure LDAP client
apt install sssd-ldap
# Point to tinsnip-host:11000 (prod) or tinsnip-host:11010 (test)
```

### For Docker Services
```yaml
environment:
  - LDAP_HOST=tinsnip-host
  - LDAP_PORT=11000  # Use 11010 for test environment
  - LDAP_BASE_DN=dc=home,dc=local
```

### Standard Port Forwarding

For clients expecting standard ports (389 for LDAP), use port forwarding:

```bash
# Forward standard LDAP port to tinsnip production
sudo iptables -t nat -A PREROUTING -p tcp --dport 389 -j REDIRECT --to-port 11000
```

## Working with Services

### Using Official Service Catalog
```bash
# Services installed to ~/.local/opt/dynamicalsystem.service/
# Deploy a service after machine setup:
sudo -u lldap-prod -i
cp -r ~/.local/opt/dynamicalsystem.service/lldap /mnt/lldap-prod/service/
cd /mnt/lldap-prod/service/lldap
docker compose up -d
```

### Creating Custom Services
Services must follow tinsnip conventions:
1. Create a service repository with your services
2. Each service needs a `docker-compose.yml` following tinsnip standards
3. Optional: Add `setup.sh` for service-specific configuration
4. Deploy using the same workflow as official services

See the [service repository](https://tangled.sh/dynamicalsystem.com/service) for examples.

## Service Repository

The official service catalog is maintained separately at:
- Repository: `git@tangled.sh:dynamicalsystem.com/service`
- Web: [https://tangled.sh/dynamicalsystem.com/service](https://tangled.sh/dynamicalsystem.com/service)

This separation allows:
- Independent service development and updates
- Organizations to maintain private service catalogs
- Clean separation between management and services

## Validation (Optional)

tinsnip includes optional validation scripts for the machine setup infrastructure:

```bash
# Run all validations (optional)
cd machine
./validate.sh
```

**Validation Coverage:**
- UID convention validation (SMEP scheme: 50000, 50100, 50200, 50300)
- Automatic port allocation and conflict prevention  
- NFS path generation for different services/environments
- XDG Base Directory compliance

Running validations before deployment is recommended but not required.

## Security Model

### SSH and NAS Access

tinsnip requires administrative access to your NAS server to create directories and NFS exports. Here's what it does:

**SSH Authentication:**
- Automatically detects and uses existing SSH keys (ssh-agent, ~/.ssh/)
- Falls back to password authentication if no keys found
- Offers to generate dedicated SSH keys for future passwordless access

**Privilege Requirements:**
- **NAS Setup**: Requires `sudo` access on NAS to create directories and configure NFS exports
- **Local Setup**: Creates system users and mounts (requires `sudo` on local machine)
- **Service Operations**: Run as dedicated service users (no elevated privileges)

**What tinsnip does on your NAS:**
- Creates service directories: `/volume1/{sheet}/{service}/{environment}/`
- Sets ownership to service-specific UIDs (10000+ range)
- Adds NFS exports to `/etc/exports` with proper permissions
- Reloads NFS exports: `exportfs -ra`

**Security practices:**
- ✅ Uses least-privilege principle (dedicated users per service)
- ✅ No permanent passwordless sudo rules created
- ✅ Service isolation via UID-based permissions
- ✅ Optional SSH key management for automation
- ❌ Never modifies system-wide sudo configuration

### Key Management

After initial setup, you can generate SSH keys for passwordless automation:

```bash
tin key generate DS412plus.local    # Generate and install SSH key
tin key list                        # Show available keys
tin key status DS412plus.local      # Test key connectivity
```

**Why this matters:**
- Initial setup requires password prompts for security
- SSH keys enable automated service deployments
- Each operation clearly indicates when elevated privileges are needed

## Design Principles

1. **Complete Isolation** - Dedicated users per service/environment
2. **Rootless Docker** - No root daemon required
3. **UID-Based Allocation** - Systematic port and user management
4. **NFS Persistence** - Data survives host rebuilds
5. **XDG Compliance** - Integrates with Linux desktop standards

## Documentation

### Core Documentation
- **[Architecture & Deployment Strategy](docs/deployment_strategy.md)** - UID schemes, port allocation, and deployment patterns
- **[Machine Setup Guide](docs/create_machine.md)** - Step-by-step infrastructure setup including NFS configuration
- **[Sheet Configuration](docs/sheet_configuration.md)** - Multi-tenant sheet system configuration
- **[Machine Registry](docs/machine_registry.md)** - Machine number assignment and registry mechanics

### Development & Integration  
- **[Service Creation Guide](docs/service_creation.md)** - How to create new services for tinsnip
- **[Service Integration Design](docs/service_integration_design.md)** - Integration patterns and best practices
- **[Service Setup Guide](docs/service_setup_guide.md)** - Comprehensive service deployment procedures
- **[Example Workflows](docs/example_workflows.md)** - Common usage patterns and examples

### Development Plans (In Progress)
- **[CLI Implementation Plan](docs/implementation_plan.md)** - Modern CLI development roadmap
- **[ATPROTO PDS Deployment](docs/atproto_pds_deployment_plan.md)** - atproto Personal Data Server deployment plan
- **[Machine Registry Updates](docs/machine-registry-update.md)** - PDS and Marshal machine integration notes

### Development
- **[Claude Code Instructions](CLAUDE.md)** - Guidance for AI-assisted development