homelab-optimized/docs/runbooks/add-new-user.md

# 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