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:

# 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):

   // 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:

   # 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:

   # 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):

# 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:

# 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

# 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)

# 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:

# 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

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

# 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

# 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)

# 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:

# 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

# 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:

# 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
• User Access Guide
• SSH Access Guide
• Authentik SSO Setup
• Security Guidelines

Change Log

• 2026-02-14 - Initial creation
• 2026-02-14 - Added comprehensive onboarding and offboarding procedures