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

Quick Start#

# 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="git@github.com: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:

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

Service Management#

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

# Configure LDAP client
apt install sssd-ldap
# Point to tinsnip-host:11000 (prod) or tinsnip-host:11010 (test)

For Docker Services#

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:

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

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

This separation allows:

• Independent service development and updates
• Organizations to maintain private service catalogs
• Clean separation between platform and applications

Planned Services#

• LLDAP - Identity Management
• Redis - Caching/queuing
• Prometheus - Metrics collection

Validation (Optional)#

tinsnip includes optional validation scripts for the machine setup infrastructure:

# 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