dynamicalsystem.com
homelab infrastructure services
1# Sheet Configuration
2
3Sheets are tinsnip's organizational unit for isolating different service deployments. Each sheet provides complete isolation with its own UID ranges, storage paths, and service deployments.
4
5## Architecture Overview
6
7**Key Design Principles:**
8- **One Global Station**: Only topsheet has a station (UID 50000) that manages registries for ALL sheets
9- **Explicit Registration**: Sheet numbers (1-4) are explicitly assigned via `tin sheet create`
10- **Shared Registry Access**: All machines mount `/mnt/station-prod` to access registries
11- **UID Isolation**: Each sheet's services use unique UID ranges based on the sheet number
12
13## Sheet Number Assignment
14
15Sheets are assigned numbers when registered:
16
17- **Sheet 1-4**: User sheets assigned sequentially via `tin sheet create`
18- **Sheet 5**: Reserved for topsheet (default/infrastructure sheet)
19
20The sheet number becomes the first digit in the SMEP UID scheme:
21- Sheet 1 services: UIDs 10000-19999
22- Sheet 2 services: UIDs 20000-29999
23- Sheet 3 services: UIDs 30000-39999
24- Sheet 4 services: UIDs 40000-49999
25- Sheet 5 (topsheet): UIDs 50000-59999
26
27## Quick Start: Working with Sheets
28
29### Default Setup (Single Sheet)
30
31Most users only need topsheet:
32
33```bash
34# First-time setup: Create topsheet station (only needed once)
35tin machine station prod <nas-server>
36
37# Create machines on topsheet (no TIN_SHEET needed - topsheet is default)
38tin machine create myservice prod <nas-server>
39tin machine create myservice dev <nas-server>
40```
41
42### Multi-Sheet Setup
43
44For multi-tenant or organization isolation:
45
46```bash
47# Step 1: Ensure topsheet station exists (only needed once for all sheets)
48tin machine station prod <nas-server>
49
50# Step 2: Register a new sheet
51tin sheet create company-a
52# Output: Sheet 'company-a' registered as sheet number 1
53
54# Step 3: Create machines on the new sheet
55TIN_SHEET=company-a tin machine create app prod <nas-server>
56TIN_SHEET=company-a tin machine create app dev <nas-server>
57
58# Step 4: Register another sheet
59tin sheet create company-b
60# Output: Sheet 'company-b' registered as sheet number 2
61
62# Step 5: Create machines on second sheet
63TIN_SHEET=company-b tin machine create app prod <nas-server>
64```
65
66## Registry Architecture
67
68The station (at `/mnt/station-prod`) maintains three registries accessible to all sheets:
69
70### 1. Sheet Registry
71**Location**: `/mnt/station-prod/data/sheets`
72
73Maps sheet names to numbers (1-4 for user sheets, 5 for topsheet):
74
75```
76topsheet=5
77company-a=1
78company-b=2
79```
80
81**Management**:
82```bash
83tin sheet create <name> # Register new sheet (auto-assigns next number)
84tin sheet list # Show all registered sheets
85tin sheet show <name> # Show sheet details
86tin sheet rm <name> # Remove sheet (cascades to all machines)
87```
88
89### 2. Machine Registries
90**Location**: `/mnt/station-prod/data/machines/<sheet>`
91
92Each sheet has its own machine registry file mapping machine names to 2-digit numbers:
93
94```
95# /mnt/station-prod/data/machines/company-a
96app=01
97database=02
98cache=03
99```
100
101Services are auto-registered when machines are created.
102
103### 3. NAS Registry
104**Location**: `/mnt/station-prod/data/nas-credentials/nas-servers`
105
106Maps sheets to their NAS servers for convenience:
107
108```
109topsheet=DS412plus.local
110company-a=nas1.company-a.com
111company-b=nas2.company-b.com
112```
113
114Allows omitting NAS server from commands after initial setup.
115
116## Sheet Detection
117
118Sheet is determined in this priority order:
119
1201. **Environment variable**: `TIN_SHEET=company-a`
1212. **System file**: `/etc/tinsnip-sheet`
1223. **Default**: `topsheet`
123
124### Setting Sheet Context
125
126**Per-command** (recommended for multi-sheet):
127```bash
128TIN_SHEET=company-a tin machine create app prod nas1.example.com
129```
130
131**Environment variable** (for session):
132```bash
133export TIN_SHEET=company-a
134tin machine create app prod nas1.example.com
135tin machine create app dev nas1.example.com
136```
137
138**System-wide** (for single sheet setups):
139```bash
140echo "company-a" | sudo tee /etc/tinsnip-sheet
141tin machine create app prod nas1.example.com # Uses company-a automatically
142```
143
144## Storage Isolation
145
146Each sheet uses separate NFS paths on the NAS:
147
148**Sheet 'company-a' (number 1):**
149```
150NAS paths:
151 /volume1/tinsnip/company-a/station/prod (if creating per-sheet station)
152 /volume1/tinsnip/company-a/app/prod
153 /volume1/tinsnip/company-a/app/dev
154
155Machine mount points:
156 /mnt/station-prod → topsheet station (shared)
157 /mnt/app-prod → /volume1/tinsnip/company-a/app/prod
158 /mnt/app-dev → /volume1/tinsnip/company-a/app/dev
159```
160
161**Sheet 'company-b' (number 2):**
162```
163NAS paths:
164 /volume1/tinsnip/company-b/app/prod
165 /volume1/tinsnip/company-b/app/dev
166
167Machine mount points:
168 /mnt/station-prod → topsheet station (shared)
169 /mnt/app-prod → /volume1/tinsnip/company-b/app/prod
170 /mnt/app-dev → /volume1/tinsnip/company-b/app/dev
171```
172
173## UID and Port Isolation
174
175The SMEP scheme ensures complete UID/port isolation:
176
177**Format**: `S-M-E-P` where:
178- `S` = Sheet number (1-5)
179- `M` = Machine number (00-99, auto-assigned)
180- `E` = Environment (0=prod, 1=test, 2=dev, etc.)
181- `P` = Port index (0-9)
182
183**Examples**:
184
185Sheet 1 (company-a):
186- `app-prod` user: UID 10100 (sheet=1, service=01, env=0, port=0)
187- `app-dev` user: UID 10120 (sheet=1, service=01, env=2, port=0)
188- Ports: 10100-10109 for app-prod, 10120-10129 for app-dev
189
190Sheet 2 (company-b):
191- `app-prod` user: UID 20100 (sheet=2, service=01, env=0, port=0)
192- `app-dev` user: UID 20120 (sheet=2, service=01, env=2, port=0)
193- Ports: 20100-20109 for app-prod, 20120-20129 for app-dev
194
195Topsheet (sheet 5):
196- `app-prod` user: UID 50100 (sheet=5, service=01, env=0, port=0)
197- Ports: 50100-50109 for app-prod
198
199## Complete Multi-Sheet Example
200
201Setting up two isolated organizations:
202
203```bash
204# === Initial Setup (Once) ===
205# Create topsheet station for registry infrastructure
206tin machine station prod DS412plus.local
207
208# === Company A Setup ===
209# Register sheet
210tin sheet create company-a
211
212# Create machines
213TIN_SHEET=company-a tin machine create web prod nas-a.example.com
214TIN_SHEET=company-a tin machine create api prod nas-a.example.com
215TIN_SHEET=company-a tin machine create db prod nas-a.example.com
216
217# Deploy services
218TIN_SHEET=company-a tin service deploy web-prod nginx
219TIN_SHEET=company-a tin service deploy api-prod myapi
220TIN_SHEET=company-a tin service deploy db-prod postgres
221
222# === Company B Setup ===
223# Register sheet
224tin sheet create company-b
225
226# Create machines (different NAS, same service names - no conflict!)
227TIN_SHEET=company-b tin machine create web prod nas-b.example.com
228TIN_SHEET=company-b tin machine create api prod nas-b.example.com
229TIN_SHEET=company-b tin machine create db prod nas-b.example.com
230
231# Deploy services
232TIN_SHEET=company-b tin service deploy web-prod nginx
233TIN_SHEET=company-b tin service deploy api-prod myapi
234TIN_SHEET=company-b tin service deploy db-prod postgres
235```
236
237**Result**:
238- Company A: UIDs 10100, 10200, 10300 / Ports 10100+, 10200+, 10300+
239- Company B: UIDs 20100, 20200, 20300 / Ports 20100+, 20200+, 20300+
240- Complete storage, UID, and port isolation
241- Both can have services with identical names without conflict
242
243## Sheet Limits
244
245- **Maximum sheets**: 4 user sheets + 1 topsheet = 5 total
246- **Rationale**: Single-digit sheet number in SMEP scheme
247- **Workaround**: For >4 sheets, deploy separate tinsnip infrastructure
248
249## NAS Configuration
250
251tinsnip automatically creates NFS exports with correct permissions during `tin machine create`. No manual NAS configuration required.
252
253**Behind the scenes** (for reference):
254
255```bash
256# On NAS, tinsnip creates exports like:
257/volume1/tinsnip/company-a/app/prod host(rw,async,no_subtree_check,all_squash,anonuid=10100,anongid=10100)
258/volume1/tinsnip/company-b/app/prod host(rw,async,no_subtree_check,all_squash,anonuid=20100,anongid=20100)
259```
260
261The `all_squash` with `anonuid` ensures all writes from the machine appear as the correct service UID on the NAS.
262
263## Troubleshooting
264
265### "Sheet not registered" error
266```bash
267[ERROR] Sheet 'mysheet' not registered
268```
269**Solution**: Register the sheet first:
270```bash
271tin sheet create mysheet
272```
273
274### "Service registry not found" error
275```bash
276[ERROR] Machine registry not found: /mnt/station-prod/data/machines/mysheet
277```
278**Solution**: Ensure topsheet station exists and sheet is registered:
279```bash
280# Check if station mounted
281mount | grep station-prod
282
283# If not, create it
284tin machine station prod <nas-server>
285
286# Then register sheet
287tin sheet create mysheet
288```
289
290### UID conflicts between sheets
291UIDs should never conflict if sheets are properly registered. Verify sheet numbers:
292```bash
293tin sheet list
294```
295
296### Cannot access registries
297All machines need `/mnt/station-prod` mounted. Verify:
298```bash
299mount | grep station-prod
300ls -la /mnt/station-prod/data/
301```
302
303If missing, ensure topsheet station was created with `tin machine station prod <nas-server>`.