Sanitized mirror from private repository - 2026-03-19 09:41:34 UTC

2026-03-19 09:41:34 +00:00
commit a98901565b
1227 changed files with 305196 additions and 0 deletions
--- a/docs/runbooks/add-new-user.md
+++ b/docs/runbooks/add-new-user.md
@@ -0,0 +1,601 @@
+# Add New User Runbook
+
+## Overview
+This runbook provides a comprehensive procedure for onboarding new users to the homelab, including network access, service authentication, and permission management. It ensures users get appropriate access while maintaining security.
+
+## Prerequisites
+- [ ] User's full name and email address
+- [ ] Desired username (lowercase, no spaces)
+- [ ] Access level determined (read-only, standard, admin)
+- [ ] Required services identified
+- [ ] Admin access to all relevant systems
+- [ ] Authentik admin access (for SSO services)
+- [ ] Tailscale admin access (for VPN)
+- [ ] Synology admin access (for file shares)
+
+## Metadata
+- **Estimated Time**: 30-60 minutes
+- **Risk Level**: Low (proper access controls in place)
+- **Requires Downtime**: No
+- **Reversible**: Yes (can remove user access)
+- **Tested On**: 2026-02-14
+
+## User Access Levels
+
+| Level | Description | Typical Use Case | Services |
+|-------|-------------|------------------|----------|
+| **Guest** | Read-only, limited services | Family, friends | Plex, Jellyfin |
+| **Standard** | Read/write, most services | Family members | Media + storage |
+| **Power User** | Advanced services | Tech-savvy users | Dev tools, monitoring |
+| **Admin** | Full access, can manage | Co-admins, yourself | Everything + admin panels |
+
+## Pre-Onboarding Checklist
+
+### Step 1: Gather Information
+
+Create a user profile document:
+
+```markdown
+# New User: [Name]
+
+**Username**: [username]
+**Email**: [email@domain.com]
+**Access Level**: [Guest/Standard/Power User/Admin]
+**Start Date**: [YYYY-MM-DD]
+
+## Services Requested:
+- [ ] Plex/Jellyfin (Media streaming)
+- [ ] File Shares (NAS access)
+- [ ] Immich (Photo backup)
+- [ ] Paperless (Document management)
+- [ ] Development tools (Gitea, etc.)
+- [ ] Monitoring dashboards
+- [ ] Other: ___________
+
+## Access Requirements:
+- [ ] Remote access (Tailscale VPN)
+- [ ] Local network only
+- [ ] Mobile apps
+- [ ] Web browser only
+
+## Notes:
+[Any special requirements or restrictions]
+```
+
+### Step 2: Plan Access
+
+Determine which systems need accounts:
+
+- [ ] **Tailscale** (VPN access to homelab)
+- [ ] **Authentik** (SSO for web services)
+- [ ] **Synology NAS** (File shares - Atlantis/Calypso)
+- [ ] **Plex** (Media streaming)
+- [ ] **Jellyfin** (Alternative media)
+- [ ] **Immich** (Photo management)
+- [ ] **Portainer** (Container management - admin only)
+- [ ] **Grafana** (Monitoring - admin/power user)
+- [ ] **Other services**: ___________
+
+## User Onboarding Procedure
+
+### Step 1: Create Tailscale Access
+
+**Why First**: Tailscale provides secure remote access to the homelab network.
+
+1. **Invite via Tailscale Admin Console**:
+   - Go to https://login.tailscale.com/admin/settings/users
+   - Click **Invite Users**
+   - Enter user's email
+   - Set expiration (optional)
+   - Click **Send Invite**
+
+2. **User receives email**:
+   - User clicks invitation link
+   - Creates Tailscale account
+   - Installs Tailscale app on their device(s)
+   - Connects to your tailnet
+
+3. **Configure ACLs** (if needed):
+   ```json
+   // In Tailscale Admin Console → Access Controls
+   {
+     "acls": [
+       // Existing ACLs...
+       {
+         "action": "accept",
+         "src": ["user@email.com"],
+         "dst": [
+           "atlantis:*",  // Allow access to Atlantis
+           "calypso:*",   // Allow access to Calypso
+           "homelab-vm:*" // Allow access to VM
+         ]
+       }
+     ]
+   }
+   ```
+
+4. **Test connectivity**:
+   ```bash
+   # Ask user to test
+   ping atlantis.your-tailnet.ts.net
+   curl http://atlantis.your-tailnet.ts.net:9000  # Test Portainer
+   ```
+
+### Step 2: Create Authentik Account (SSO)
+
+**Purpose**: Single sign-on for most web services.
+
+1. **Access Authentik Admin**:
+   - Navigate to your Authentik instance
+   - Log in as admin
+
+2. **Create User**:
+   - **Directory** → **Users** → **Create**
+   - Fill in:
+     - **Username**: `username` (lowercase)
+     - **Name**: `First Last`
+     - **Email**: `user@email.com`
+     - **Groups**: Add to appropriate groups
+       - `homelab-users` (standard access)
+       - `homelab-admins` (for admin users)
+       - Service-specific groups (e.g., `jellyfin-users`)
+
+3. **Set Password**:
+   - Option A: Set temporary password, force change on first login
+   - Option B: Send password reset link via email
+
+4. **Assign Service Access**:
+   - **Applications** → **Outposts**
+   - For each service the user should access:
+     - Edit application
+     - Add user/group to **Policy Bindings**
+
+5. **Test SSO**:
+   ```bash
+   # User should test login to SSO-enabled services
+   # Example: Grafana, Jellyseerr, etc.
+   ```
+
+### Step 3: Create Synology NAS Account
+
+**Purpose**: Access to file shares, Photos, Drive, etc.
+
+#### On Atlantis (Primary NAS):
+
+```bash
+# SSH to Atlantis
+ssh admin@atlantis
+
+# Create user (DSM 7.x)
+# Via DSM UI (recommended):
+```
+
+1. **Control Panel** → **User & Group** → **User** → **Create**
+2. Fill in:
+   - **Name**: `username`
+   - **Description**: `[Full Name]`
+   - **Email**: `user@email.com`
+   - **Password**: Set strong password
+3. **Join Groups**:
+   - `users` (default)
+   - `http` (if web service access needed)
+4. **Configure Permissions**:
+   - **Applications** tab:
+     - [ ] Synology Photos (if needed)
+     - [ ] Synology Drive (if needed)
+     - [ ] File Station
+     - [ ] Other apps as needed
+   - **Shared Folders** tab:
+     - Set permissions for each share:
+       - Read/Write: For shares user can modify
+       - Read-only: For media libraries
+       - No access: For restricted folders
+5. **User Quotas** (optional):
+   - Set storage quota if needed
+   - Limit upload/download speed if needed
+6. **Click Create**
+
+#### On Calypso (Secondary NAS):
+
+Repeat the same process if user needs access to Calypso.
+
+**Alternative: SSH Method**:
+```bash
+# Create user via command line
+sudo synouser --add username "Full Name" "password" "user@email.com" 0 "" 0
+
+# Add to groups
+sudo synogroup --member users username add
+
+# Set folder permissions (example)
+sudo chown -R username:users /volume1/homes/username
+```
+
+### Step 4: Create Plex Account
+
+**Option A: Managed User (Recommended for Family)**
+
+1. Open Plex Web
+2. **Settings** → **Users & Sharing** → **Manage Home Users**
+3. Click **Add User**
+4. Set:
+   - **Username**: `[Name]`
+   - **PIN**: 4-digit PIN
+   - Enable **Managed user** if restricted access desired
+5. Configure library access
+
+**Option B: Plex Account (For External Users)**
+
+1. User creates their own Plex account
+2. **Settings** → **Users & Sharing** → **Friends**
+3. Invite by email
+4. Select libraries to share
+5. Configure restrictions:
+   - [ ] Allow sync
+   - [ ] Allow camera upload
+   - [ ] Rating restrictions (if children)
+
+### Step 5: Create Jellyfin Account
+
+```bash
+# SSH to host running Jellyfin
+ssh atlantis  # or wherever Jellyfin runs
+
+# Or via web UI:
+```
+
+1. Open Jellyfin web interface
+2. **Dashboard** → **Users** → **Add User**
+3. Set:
+   - **Name**: `username`
+   - **Password**: REDACTED_PASSWORD password
+4. Configure:
+   - **Library access**: Select which libraries
+   - **Permissions**:
+     - [ ] Allow media deletion
+     - [ ] Allow remote access
+     - [ ] Enable live TV (if applicable)
+5. **Save**
+
+### Step 6: Create Immich Account (If Used)
+
+```bash
+# Via Immich web interface
+```
+
+1. Open Immich
+2. **Administration** → **Users** → **Create User**
+3. Set:
+   - **Email**: `user@email.com`
+   - **Password**: REDACTED_PASSWORD password
+   - **Name**: `Full Name`
+4. User logs in and sets up mobile app
+
+### Step 7: Grant Service-Specific Access
+
+#### Gitea (Development)
+
+1. Gitea web interface
+2. **Site Administration** → **User Accounts** → **Create User Account**
+3. Fill in details
+4. Add to appropriate organizations/teams
+
+#### Portainer (Admin/Power Users Only)
+
+1. Portainer web interface
+2. **Users** → **Add user**
+3. Set:
+   - **Username**: `username`
+   - **Password**: REDACTED_PASSWORD password
+4. Assign role:
+   - **Administrator**: Full access
+   - **Operator**: Can manage containers
+   - **User**: Read-only
+5. Assign to teams/endpoints
+
+#### Grafana (Monitoring)
+
+If using Authentik SSO, user automatically gets access.
+
+If not using SSO:
+1. Grafana web interface
+2. **Configuration** → **Users** → **Invite**
+3. Set role:
+   - **Viewer**: Read-only dashboards
+   - **Editor**: Can create dashboards
+   - **Admin**: Full access
+
+### Step 8: Configure Mobile Apps
+
+Provide user with setup instructions:
+
+**Plex**:
+- Download Plex app
+- Sign in with Plex account
+- Server should auto-discover via Tailscale
+
+**Jellyfin**:
+- Download Jellyfin app
+- Add server: `http://atlantis.tailnet:8096`
+- Sign in with credentials
+
+**Immich** (if used):
+- Download Immich app
+- Server: `http://atlantis.tailnet:2283`
+- Enable auto-backup (optional)
+
+**Synology Apps**:
+- DS File (file access)
+- Synology Photos
+- DS Audio/Video
+- Server: `atlantis.tailnet` or QuickConnect ID
+
+**Tailscale**:
+- Already installed in Step 1
+- Ensure "Always On VPN" enabled for seamless access
+
+## User Documentation Package
+
+Provide new user with documentation:
+
+```markdown
+# Welcome to the Homelab!
+
+Hi [Name],
+
+Your access has been set up. Here's what you need to know:
+
+## Network Access
+
+**Tailscale VPN**:
+- Install Tailscale from: https://tailscale.com/download
+- Log in with your account (check email for invitation)
+- Connect to our tailnet
+- You can now access services remotely!
+
+## Available Services
+
+### Media Streaming
+- **Plex**: https://plex.vish.gg
+  - Username: [plex-username]
+  - Watch movies, TV shows, music
+
+- **Jellyfin**: https://jellyfin.vish.gg
+  - Username: [username]
+  - Alternative media server
+
+### File Storage
+- **Atlantis NAS**: smb://atlantis.tailnet/[your-folder]
+  - Access via file explorer
+  - Windows: \\atlantis.tailnet\folder
+  - Mac: smb://atlantis.tailnet/folder
+
+### Photos
+- **Immich**: https://immich.vish.gg
+  - Auto-backup from your phone
+  - Private photo storage
+
+### Other Services
+- [List other services user has access to]
+
+## Support
+
+If you need help:
+- Email: [your-email]
+- [Alternative contact method]
+
+## Security
+
+- Don't share passwords
+- Enable 2FA where available
+- Report any suspicious activity
+
+Welcome aboard!
+```
+
+## Post-Onboarding Tasks
+
+### Step 1: Update Documentation
+
+```bash
+cd ~/Documents/repos/homelab
+
+# Update user access documentation
+nano docs/infrastructure/USER_ACCESS_GUIDE.md
+
+# Add user to list:
+# | Username | Access Level | Services | Status |
+# | username | Standard | Plex, Files, Photos | ✅ Active |
+
+git add .
+git commit -m "Add new user: [username]"
+git push
+```
+
+### Step 2: Test User Access
+
+Verify everything works:
+- [ ] User can connect via Tailscale
+- [ ] User can access Plex/Jellyfin
+- [ ] User can access file shares
+- [ ] SSO login works
+- [ ] Mobile apps working
+- [ ] No access to restricted services
+
+### Step 3: Monitor Usage
+
+```bash
+# Check user activity after a few days
+# Grafana dashboards should show:
+# - Network traffic from user's IP
+# - Service access logs
+# - Any errors
+
+# Review logs
+ssh atlantis
+grep username /var/log/auth.log  # SSH attempts
+docker logs plex | grep username  # Plex usage
+```
+
+## Verification Checklist
+
+- [ ] Tailscale invitation sent and accepted
+- [ ] Authentik account created and tested
+- [ ] Synology NAS account created (Atlantis/Calypso)
+- [ ] Plex/Jellyfin access granted
+- [ ] Required service accounts created
+- [ ] Mobile apps configured and tested
+- [ ] User documentation sent
+- [ ] User confirmed access is working
+- [ ] Documentation updated
+- [ ] No access to restricted services
+
+## User Removal Procedure
+
+When user no longer needs access:
+
+### Step 1: Disable Accounts
+
+```bash
+# Disable in order of security priority:
+
+# 1. Tailscale
+# Admin Console → Users → [user] → Revoke keys
+
+# 2. Authentik
+# Directory → Users → [user] → Deactivate
+
+# 3. Synology NAS
+# Control Panel → User & Group → [user] → Disable
+# Or via SSH:
+sudo synouser --disable username
+
+# 4. Plex
+# Settings → Users & Sharing → Remove user
+
+# 5. Jellyfin
+# Dashboard → Users → [user] → Delete
+
+# 6. Other services
+# Remove from each service individually
+```
+
+### Step 2: Archive User Data (Optional)
+
+```bash
+# Backup user's data before deleting
+# Synology home folder:
+tar czf /volume1/backups/user-archives/username-$(date +%Y%m%d).tar.gz \
+    /volume1/homes/username
+
+# User's Immich photos (if applicable)
+# User's documents (if applicable)
+```
+
+### Step 3: Delete User
+
+After confirming data is backed up:
+
+```bash
+# Synology: Delete user
+# Control Panel → User & Group → [user] → Delete
+# Choose whether to keep or delete user's data
+
+# Or via SSH:
+sudo synouser --del username
+sudo rm -rf /volume1/homes/username  # If deleting data
+```
+
+### Step 4: Update Documentation
+
+```bash
+# Update user access guide
+nano docs/infrastructure/USER_ACCESS_GUIDE.md
+# Mark user as removed with date
+
+git add .
+git commit -m "Remove user: [username] - access terminated [date]"
+git push
+```
+
+## Troubleshooting
+
+### Issue: User Can't Connect via Tailscale
+
+**Solutions**:
+- Verify invitation was accepted
+- Check user installed Tailscale correctly
+- Verify ACLs allow user's device
+- Check user's device firewall
+- Try: `tailscale ping atlantis`
+
+### Issue: SSO Login Not Working
+
+**Solutions**:
+- Verify Authentik account is active
+- Check user is in correct groups
+- Verify application is assigned to user
+- Clear browser cookies
+- Try incognito mode
+- Check Authentik logs
+
+### Issue: Can't Access File Shares
+
+**Solutions**:
+```bash
+# Check Synology user exists and is enabled
+ssh atlantis
+sudo synouser --get username
+
+# Check folder permissions
+ls -la /volume1/homes/username
+
+# Check SMB service is running
+sudo synoservicectl --status smbd
+
+# Test from user's machine:
+smbclient -L atlantis.tailnet -U username
+```
+
+### Issue: Plex Not Showing Up for User
+
+**Solutions**:
+- Verify user accepted Plex sharing invitation
+- Check library access permissions
+- Verify user's account email is correct
+- Try removing and re-adding the user
+- Check Plex server accessibility
+
+## Best Practices
+
+### Security
+- Use strong passwords (12+ characters, mixed case, numbers, symbols)
+- Enable 2FA where available (Authentik supports it)
+- Least privilege principle (only grant needed access)
+- Regular access reviews (quarterly)
+- Disable accounts promptly when not needed
+
+### Documentation
+- Keep user list up to date
+- Document special access grants
+- Note user role changes
+- Archive user data before deletion
+
+### Communication
+- Set clear expectations with users
+- Provide good documentation
+- Be responsive to access issues
+- Notify users of maintenance windows
+
+## Related Documentation
+
+- [Infrastructure Overview](../infrastructure/INFRASTRUCTURE_OVERVIEW.md)
+- [User Access Guide](../infrastructure/USER_ACCESS_GUIDE.md)
+- [SSH Access Guide](../infrastructure/SSH_ACCESS_GUIDE.md)
+- [Authentik SSO Setup](../infrastructure/authentik-sso.md)
+- [Security Guidelines](../infrastructure/security.md)
+
+## Change Log
+
+- 2026-02-14 - Initial creation
+- 2026-02-14 - Added comprehensive onboarding and offboarding procedures