dynamicalsystem.com
homelab infrastructure services
1# tinsnip - Homelab Infrastructure Platform
2
3Provides opinionated container management which standardizes how services are configured, deployed, and managed in homelab environments.
4
5## Overview
6
7tinsnip provides the infrastructure foundation for deploying services with:
8- **Standardized UIDs** following the SMEP scheme for proper NFS permissions
9- **NFS-backed persistence** for config, data, and state
10- **XDG integration** via symbolic links in standard locations
11- **Rootless Docker** with consistent host-to-container data mapping
12- **Service isolation** through dedicated users and namespaces
13
14## Service Catalog
15
16Services are maintained in a separate repository.
17
18See: [https://tangled.sh/dynamicalsystem.com/service](https://tangled.sh/dynamicalsystem.com/service)
19
20To 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.
21
22## Quick Start
23
24### Install tinsnip
25```bash
26# Install tinsnip with service catalog
27curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | INSTALL_SERVICES=true bash
28
29# Add to PATH
30export PATH="$HOME/.local/opt/dynamicalsystem.tinsnip/bin:$PATH"
31echo 'export PATH="$HOME/.local/opt/dynamicalsystem.tinsnip/bin:$PATH"' >> ~/.bashrc
32```
33
34### Legacy Script Interface (Still Supported)
35
36```bash
37# Install with custom service catalog
38curl -fsSL "https://tangled.sh/dynamicalsystem.com/tinsnip/raw/main/install.sh?$(date +%s)" | \
39 SERVICE_REPO_URL="git@github.com:mycompany/services" INSTALL_SERVICES=true bash
40
41# Use scripts directly
42cd ~/.local/opt/dynamicalsystem.tinsnip
43./machine/setup.sh gateway prod DS412plus.local
44```
45
46## Architecture
47
48tinsnip uses a multi-environment deployment model with:
49
50- **Service Isolation**: Each service runs under dedicated users (UID 11000+ range)
51- **Environment Separation**: Separate prod/test deployments with different UIDs and ports
52- **Namespace Support**: Configurable namespaces, called sheets, for multi-tenant deployments (defaults to `sheet`)
53- **Rootless Docker**: Complete container isolation without root privileges
54- **NFS-Backed Storage**: Persistent data across host rebuilds
55- **Automatic Port Allocation**: SMEP-based numbering prevents UID and port conflicts
56
57### UID and Port Convention
58
59Machines follow a 5-digit numbering scheme (`SMEP`) for both UIDs and ports:
60
61| Machine | Environment | UID (P=0) | Port Range | Primary Port | Secondary Port |
62|---------|-------------|-----------|------------|--------------|----------------|
63| station | prod | 11000 | 11000-11009 | 11000 | 11001 |
64| station | test | 11010 | 11010-11019 | 11010 | 11011 |
65| lldap | prod | 11200 | 11200-11209 | 11200 | 11201 |
66| lldap | test | 11210 | 11210-11219 | 11210 | 11211 |
67
68For 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).
69
70## CLI Reference
71
72The `tin` command provides a modern interface for tinsnip operations:
73
74### Core Commands
75```bash
76tin sheet <name> # Create/register sheet
77tin machine <service> <env> # Create service machine environment
78tin service <service-env> <name> # Deploy service to machine
79
80# Examples
81tin sheet infrastructure # Register infrastructure sheet
82tin machine gazette prod # Create gazette-prod (auto-discover NAS)
83tin service gazette-prod lldap # Deploy lldap to gazette-prod
84```
85
86### Management Commands
87```bash
88tin registry # Manage registries (sheets, NAS servers)
89tin key # Manage SSH keys for NAS access
90tin status # Show tinsinp status
91tin help # Show help information
92```
93
94### Registry Management
95```bash
96tin sheet list # List registered sheets
97tin sheet show <name> # Show sheet details
98tin registry service list # List services in current sheet
99tin key generate <nas-server> # Generate SSH key for NAS server
100```
101
102## Service Management
103
104### Using CLI Commands
105```bash
106# Deploy services
107tin service gateway-prod lldap # Deploy LLDAP to gateway-prod
108tin status # Show all service status
109tin service gateway-prod logs lldap # View service logs
110
111# Registry management
112tin registry service list # List services in current sheet
113tin sheet list # List all sheets
114```
115
116### Legacy Direct Management
117```bash
118# Switch to service user
119sudo -u gateway-prod -i
120
121# Check service status
122cd /mnt/gateway-prod/service/lldap
123docker compose ps
124
125# View logs
126docker compose logs -f
127```
128
129## Integration Guide
130
131### LLDAP Configuration
132- **Base DN**: `dc=home,dc=local`
133- **Production**: `tinsnip-host:11000` (LDAP), `tinsnip-host:11001` (Web UI)
134- **Test**: `tinsnip-host:11010` (LDAP), `tinsnip-host:11011` (Web UI)
135
136### For Ubuntu/Debian Systems
137```bash
138# Configure LDAP client
139apt install sssd-ldap
140# Point to tinsnip-host:11000 (prod) or tinsnip-host:11010 (test)
141```
142
143### For Docker Services
144```yaml
145environment:
146 - LDAP_HOST=tinsnip-host
147 - LDAP_PORT=11000 # Use 11010 for test environment
148 - LDAP_BASE_DN=dc=home,dc=local
149```
150
151### Standard Port Forwarding
152
153For clients expecting standard ports (389 for LDAP), use port forwarding:
154
155```bash
156# Forward standard LDAP port to tinsnip production
157sudo iptables -t nat -A PREROUTING -p tcp --dport 389 -j REDIRECT --to-port 11000
158```
159
160## Working with Services
161
162### Using Official Service Catalog
163```bash
164# Services installed to ~/.local/opt/dynamicalsystem.service/
165# Deploy a service after machine setup:
166sudo -u lldap-prod -i
167cp -r ~/.local/opt/dynamicalsystem.service/lldap /mnt/lldap-prod/service/
168cd /mnt/lldap-prod/service/lldap
169docker compose up -d
170```
171
172### Creating Custom Services
173Services must follow tinsnip conventions:
1741. Create a service repository with your services
1752. Each service needs a `docker-compose.yml` following tinsnip standards
1763. Optional: Add `setup.sh` for service-specific configuration
1774. Deploy using the same workflow as official services
178
179See the [service repository](https://tangled.sh/dynamicalsystem.com/service) for examples.
180
181## Service Repository
182
183The official service catalog is maintained separately at:
184- Repository: `git@tangled.sh:dynamicalsystem.com/service`
185- Web: [https://tangled.sh/dynamicalsystem.com/service](https://tangled.sh/dynamicalsystem.com/service)
186
187This separation allows:
188- Independent service development and updates
189- Organizations to maintain private service catalogs
190- Clean separation between management and services
191
192## Validation (Optional)
193
194tinsnip includes optional validation scripts for the machine setup infrastructure:
195
196```bash
197# Run all validations (optional)
198cd machine
199./validate.sh
200```
201
202**Validation Coverage:**
203- UID convention validation (SMEP scheme: 50000, 50100, 50200, 50300)
204- Automatic port allocation and conflict prevention
205- NFS path generation for different services/environments
206- XDG Base Directory compliance
207
208Running validations before deployment is recommended but not required.
209
210## Security Model
211
212### SSH and NAS Access
213
214tinsnip requires administrative access to your NAS server to create directories and NFS exports. Here's what it does:
215
216**SSH Authentication:**
217- Automatically detects and uses existing SSH keys (ssh-agent, ~/.ssh/)
218- Falls back to password authentication if no keys found
219- Offers to generate dedicated SSH keys for future passwordless access
220
221**Privilege Requirements:**
222- **NAS Setup**: Requires `sudo` access on NAS to create directories and configure NFS exports
223- **Local Setup**: Creates system users and mounts (requires `sudo` on local machine)
224- **Service Operations**: Run as dedicated service users (no elevated privileges)
225
226**What tinsnip does on your NAS:**
227- Creates service directories: `/volume1/{sheet}/{service}/{environment}/`
228- Sets ownership to service-specific UIDs (10000+ range)
229- Adds NFS exports to `/etc/exports` with proper permissions
230- Reloads NFS exports: `exportfs -ra`
231
232**Security practices:**
233- ✅ Uses least-privilege principle (dedicated users per service)
234- ✅ No permanent passwordless sudo rules created
235- ✅ Service isolation via UID-based permissions
236- ✅ Optional SSH key management for automation
237- ❌ Never modifies system-wide sudo configuration
238
239### Key Management
240
241After initial setup, you can generate SSH keys for passwordless automation:
242
243```bash
244tin key generate DS412plus.local # Generate and install SSH key
245tin key list # Show available keys
246tin key status DS412plus.local # Test key connectivity
247```
248
249**Why this matters:**
250- Initial setup requires password prompts for security
251- SSH keys enable automated service deployments
252- Each operation clearly indicates when elevated privileges are needed
253
254## Design Principles
255
2561. **Complete Isolation** - Dedicated users per service/environment
2572. **Rootless Docker** - No root daemon required
2583. **UID-Based Allocation** - Systematic port and user management
2594. **NFS Persistence** - Data survives host rebuilds
2605. **XDG Compliance** - Integrates with Linux desktop standards
261
262## Documentation
263
264### Core Documentation
265- **[Architecture & Deployment Strategy](docs/deployment_strategy.md)** - UID schemes, port allocation, and deployment patterns
266- **[Machine Setup Guide](docs/create_machine.md)** - Step-by-step infrastructure setup including NFS configuration
267- **[Sheet Configuration](docs/sheet_configuration.md)** - Multi-tenant sheet system configuration
268- **[Machine Registry](docs/machine_registry.md)** - Machine number assignment and registry mechanics
269
270### Development & Integration
271- **[Service Creation Guide](docs/service_creation.md)** - How to create new services for tinsnip
272- **[Service Integration Design](docs/service_integration_design.md)** - Integration patterns and best practices
273- **[Service Setup Guide](docs/service_setup_guide.md)** - Comprehensive service deployment procedures
274- **[Example Workflows](docs/example_workflows.md)** - Common usage patterns and examples
275
276### Development Plans (In Progress)
277- **[CLI Implementation Plan](docs/implementation_plan.md)** - Modern CLI development roadmap
278- **[ATPROTO PDS Deployment](docs/atproto_pds_deployment_plan.md)** - atproto Personal Data Server deployment plan
279- **[Machine Registry Updates](docs/machine-registry-update.md)** - PDS and Marshal machine integration notes
280
281### Development
282- **[Claude Code Instructions](CLAUDE.md)** - Guidance for AI-assisted development