dynamicalsystem.com
homelab infrastructure services
1# Implementation Plan: tinsnip CLI Evolution
2
3## Overview
4Transform tinsnip from script-based to modern CLI with centralized sheet management, automated NAS credential handling, and improved UX.
5
6## Phase 1: Bootstrap topsheet (Foundation)
7
8### 1.1 Create topsheet Infrastructure
9**Goal**: Establish reserved sheet 5 (topsheet) for tinsnip infrastructure services
10
11**Tasks**:
12- [x] Update `lib/uid.sh` to reserve sheet 5 for topsheet
13- [x] Modify sheet number calculation to handle reserved sheet
14- [x] Create topsheet bootstrap capability
15
16**Files modified**:
17- `lib/uid.sh`: Added `get_sheet_number()` reservation logic for topsheet
18- Machine setup: Added special handling for topsheet
19
20**Implementation**:
21```bash
22# In lib/uid.sh
23get_sheet_number() {
24 local sheet="${1:-${TIN_SHEET:-topsheet}}"
25 if [[ "$sheet" == "topsheet" ]]; then
26 echo "5" # Reserved for topsheet
27 return
28 fi
29 # Registry lookup for user sheets (1-4)
30}
31```
32
33### 1.2 Create topsheet.station-prod Service
34**Goal**: Deploy the special station with global registries
35
36**Tasks**:
37- [ ] Create `service/station/` directory structure
38- [ ] Create `docker-compose.yml` for station service
39- [ ] Add registry initialization scripts
40- [ ] Set up NAS credential storage structure
41
42**Files to create**:
43- `service/station/docker-compose.yml`
44- `service/station/setup.sh`
45- `service/station/scripts/init-registries.sh`
46
47**Registry Structure**:
48```bash
49/volume1/topsheet/station/prod/data/
50├── sheets # Global sheet registry
51├── services/ # Per-sheet service registries
52│ └── topsheet # topsheet services registry
53└── nas-credentials/ # SSH keys for NAS access
54 ├── DS412plus.key
55 └── authorized_keys
56```
57
58## Phase 2: Sheet Registry Implementation
59
60### 2.1 Collision Detection and Registry
61**Goal**: Prevent sheet number collisions
62
63**Tasks**:
64- [ ] Create sheet collision detection in `lib.sh`
65- [ ] Implement registry consultation before assignment
66- [ ] Add registry update functions
67- [ ] Create sheet registration workflow
68
69**Files to modify**:
70- `machine/scripts/lib.sh`: Add registry functions
71- `machine/setup.sh`: Add collision checking
72
73**Implementation**:
74```bash
75# In lib/registry.sh
76register_sheet_in_registry() {
77 local sheet="$1"
78 local number="$2"
79 local registry="/mnt/station-prod/data/sheets"
80
81 # Check if already registered
82 if grep -q "^${sheet}=" "$registry" 2>/dev/null; then
83 error "Sheet already registered"
84 return 1
85 fi
86
87 # Add to registry (user sheets use 1-4, topsheet is 5)
88 echo "${sheet}=${number}" >> "$registry"
89}
90```
91
92### 2.2 Update Existing Sheet Functions
93**Goal**: Make all sheet operations registry-aware
94
95**Tasks**:
96- [ ] Modify `get_sheet_number()` to consult registry
97- [ ] Update all scripts to use registry-based assignment
98- [ ] Add validation for sheet conflicts
99
100## Phase 3: NAS Credential Management
101
102### 3.1 SSH Key Infrastructure
103**Goal**: Eliminate interactive password prompts
104
105**Tasks**:
106- [ ] Create SSH key generation and distribution system
107- [ ] Modify NAS setup scripts to use stored keys
108- [ ] Add key management functions to tinsnip.station-prod
109
110**Files to modify**:
111- `machine/scripts/mount_nas.sh`: Replace password logic with key-based auth
112- `service/station/scripts/manage-nas-keys.sh`: New key management script
113
114**Implementation**:
115```bash
116# In mount_nas.sh
117setup_nas_exports() {
118 local nas_server="$1"
119 local ssh_key="/volume1/tinsnip/station-prod/data/nas-credentials/${nas_server}.key"
120
121 # Use stored SSH key instead of prompting for password
122 ssh -i "$ssh_key" "$nas_server" "sudo mkdir -p '$nfs_export'"
123}
124```
125
126### 3.2 Automated NAS Discovery
127**Goal**: Remove NAS parameter from machine setup
128
129**Tasks**:
130- [ ] Create NAS server registry in tinsnip.station-prod
131- [ ] Implement NAS auto-discovery based on sheet
132- [ ] Update machine setup to query NAS from registry
133
134**Registry Structure**:
135```bash
136/volume1/topsheet/station/prod/data/nas-credentials/nas-servers
137# Format: sheet=nas_server
138topsheet=DS412plus.local
139infrastructure=DS412plus.local
140mycompany=nas2.company.com
141```
142
143## Phase 4: Modern CLI Implementation
144
145### 4.1 Create `tin` Command Structure
146**Goal**: Replace script-based workflow with modern CLI
147
148**Tasks**:
149- [ ] Create `bin/tin` main CLI script
150- [ ] Implement subcommand routing
151- [ ] Add verbless command pattern
152- [ ] Create help system
153
154**Files to create**:
155- `bin/tin`: Main CLI entry point
156- `bin/tin-sheet`: Sheet management subcommand
157- `bin/tin-machine`: Machine setup subcommand
158- `bin/tin-service`: Service deployment subcommand
159
160**CLI Structure**:
161```bash
162#!/bin/bash
163# bin/tin
164case "$1" in
165 sheet) shift; exec tin-sheet "$@" ;;
166 machine) shift; exec tin-machine "$@" ;;
167 service) shift; exec tin-service "$@" ;;
168 *) tin-help ;;
169esac
170```
171
172### 4.2 Implement Subcommands
173**Goal**: Create intuitive verbless commands
174
175**Tasks**:
176- [ ] `tin sheet <name>`: Register new sheet
177- [ ] `tin machine <service> <env>`: Create service environment
178- [ ] `tin service <service-env> <catalog-entry>`: Deploy service
179- [ ] Add `list`, `status`, `remove` variations
180
181**Command Examples**:
182```bash
183# Most users just use topsheet (default)
184tin machine gazette prod DS412plus # Create gazette-prod in topsheet
185tin service gazette-prod lldap # Deploy lldap to gazette-prod
186
187# Advanced: Register additional sheets for multi-tenant
188tin sheet infrastructure # Register user sheet
189TIN_SHEET=infrastructure tin machine gazette prod
190```
191
192## Phase 5: Service Catalog Integration
193
194### 5.1 Move Service Catalog to topsheet.station-prod
195**Goal**: Centralize service definitions
196
197**Tasks**:
198- [ ] Migrate service catalog from separate repo to topsheet.station-prod
199- [ ] Update service deployment to use centralized catalog
200- [ ] Add catalog management commands
201
202**Structure**:
203```bash
204/volume1/topsheet/station/prod/data/catalog/
205├── lldap/
206│ ├── docker-compose.yml
207│ └── setup.sh
208├── redis/
209└── prometheus/
210```
211
212### 5.2 Service Deployment Automation
213**Goal**: Streamline service deployment
214
215**Tasks**:
216- [ ] Implement automatic service copying from catalog
217- [ ] Add environment variable generation
218- [ ] Create service status monitoring
219
220## Phase 6: Migration and Documentation
221
222### 6.1 Backward Compatibility
223**Goal**: Ensure existing deployments continue working
224
225**Tasks**:
226- [ ] Create migration script for existing installations
227- [ ] Add legacy command compatibility layer
228- [ ] Update all documentation
229
230### 6.2 Documentation Updates
231**Goal**: Document new CLI and architecture
232
233**Tasks**:
234- [ ] Update `CLAUDE.md` with new workflow
235- [ ] Create CLI reference documentation
236- [ ] Add migration guide from script-based to CLI-based workflow
237
238## Implementation Order
239
2401. **✅ Phase 1 COMPLETED**: Bootstrap topsheet and station infrastructure
2412. **✅ Phase 2 COMPLETED**: Registry functionality to prevent collisions
2423. **✅ Phase 3 COMPLETED**: NAS credential management infrastructure
2434. **✅ Phase 4 COMPLETED**: Modern CLI interface
2445. **Phase 5 IN PROGRESS**: Service catalog integration
2456. **Phase 6 PENDING**: Migration and documentation
246
247Each phase builds on the previous and can be tested independently. Most users will deploy all services to topsheet (the default). Advanced multi-tenant setups can use additional sheets (1-4).
248
249## Architecture Summary
250
251### Before (Current)
252- Script-based workflow with manual NAS parameter
253- Hash-based sheet numbers (collision-prone)
254- Interactive password prompts for NAS access
255- Separate service catalog repository
256- Manual service deployment
257
258### After (Current Implementation)
259- ✅ Modern CLI with verbless commands
260- ✅ Registry-based sheet management (collision-free)
261- ✅ SSH key infrastructure for NAS access
262- 🚧 Centralized service catalog in topsheet.station-prod (in progress)
263- 🚧 Automated service deployment with auto-discovery (in progress)
264
265### Key Benefits Achieved
266- **UX**: Simple commands with sensible defaults
267- **Security**: SSH key infrastructure available
268- **Reliability**: Registry prevents UID/port collisions
269- **Flexibility**: topsheet for most users, additional sheets for advanced multi-tenant scenarios
270- **Consistency**: Standardized SMEP UID scheme across all deployments