tinsnip / README.md

# tinsnip - Homelab Infrastructure Platform

An opinionated service deployment platform that 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 TNSEP 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. Example services include:
- **LLDAP** - Lightweight identity management
- **Redis** - Caching and queuing (planned)
- **Prometheus** - Metrics collection (planned)

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

## Quick Start

```bash
# Install tinsnip platform only
curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | bash

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

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

## 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 for multi-tenant deployments (defaults to `dynamicalsystem`)
- **Rootless Docker**: Complete container isolation without root privileges
- **NFS-Backed Storage**: Persistent data across host rebuilds
- **Automatic Port Allocation**: UID-based port assignment prevents conflicts

### UID and Port Convention

Services follow a 5-digit UID scheme (`TNSEP`) with automatic port allocation:

| Service | Environment | UID | Primary Port | Secondary Port |
|---------|-------------|-----|--------------|----------------|
| station | prod | 11000 | 11000 | 11001 |
| station | test | 11010 | 11010 | 11011 |
| lldap | prod | 11200 | 11200 | 11201 |
| lldap | test | 11210 | 11210 | 11211 |

For details on UID conventions, port allocation, and deployment patterns, see [DEPLOYMENT_STRATEGY.md](DEPLOYMENT_STRATEGY.md). For step-by-step machine setup including NFS configuration, see [CREATE_MACHINE.md](CREATE_MACHINE.md). For namespace configuration options, see [NAMESPACE_CONFIGURATION.md](NAMESPACE_CONFIGURATION.md). For service registry mechanics and service number assignment, see [SERVICE_REGISTRY.md](SERVICE_REGISTRY.md).

## Service Management

```bash
# Switch to tinsnip user
sudo -u tinsnip -i

# Check service status  
cd ~/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/docker/service/
cd /mnt/docker/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: `[e-mail]: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 platform and applications

## Planned Services

- [x] LLDAP - Identity Management
- [ ] Redis - Caching/queuing  
- [ ] Prometheus - Metrics collection

## 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 (TNSEP scheme: 11000, 11010, 11100, 11110)
- 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.

## 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