dynamicalsystem.com / tinsnip
homelab infrastructure services
fork atom
Shell 99.3%
Other 0.7%
171 2 1

Clone this repository

https://tangled.org/dynamicalsystem.com/tinsnip https://tangled.org/did:plc:3sdo5wodzmtltyysmeynifk3/tinsnip
git@tangled.org:dynamicalsystem.com/tinsnip git@tangled.org:did:plc:3sdo5wodzmtltyysmeynifk3/tinsnip

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

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

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#

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

# 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. For step-by-step machine setup including NFS configuration, see create_machine.md. For sheet configuration options, see sheet_configuration.md. For machine registry mechanics and machine number assignment, see machine_registry.md.

CLI Reference#

The tin command provides a modern interface for tinsnip operations:

Core Commands#

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#

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#

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#

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

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

# 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/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 for examples.

Service Repository#

The official service catalog is maintained separately at:

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:

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

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#

Development & Integration#

Development Plans (In Progress)#

Development#