claude-home/server-configs/termix/README.md

# Termix - SSH Server Management Platform

**LXC 210 (n8n)** | **10.10.0.210:8180** | **termix.manticorum.com**

Self-hosted, open-source alternative to Termius for comprehensive SSH server management with web-based terminal, file management, Docker control, and monitoring.

## Quick Info

| Property | Value |
|----------|-------|
| **Type** | Docker container on n8n LXC |
| **Host OS** | Ubuntu (LXC 210) |
| **Host IP** | 10.10.0.210 |
| **Port** | 8180 (internal) |
| **Public URL** | https://termix.manticorum.com |
| **Termix Version** | 1.11.0 (via Docker) |
| **Reverse Proxy** | Nginx Proxy Manager (10.10.0.16) |

## Deployment Details

- **Deployed on**: Existing n8n LXC (210) to save resources
- **Shares container with**: n8n, omni-tools
- **Docker compose**: `/opt/termix/docker-compose.yml`
- **Data directory**: `/opt/termix/data/`

## Services

### Termix Web App
- **Port**: 8080 (internal)
- **Tech Stack**: TypeScript/React, SQLite database
- **Data**: `/opt/termix/data` (encrypted SQLite)
- **Config**: Environment variables in docker-compose

### Docker Engine
- Required to run Termix container
- Manages Termix app lifecycle

## Management

### Access Container
```bash
ssh root@10.10.0.210
# or via Proxmox
pct enter 210
```

### Service Management
```bash
# Status
cd /opt/termix
docker compose ps

# Restart
docker compose restart

# Logs
docker compose logs -f

# Stop/Start
docker compose down
docker compose up -d
```

### View Termix Logs
```bash
docker compose logs -f termix
```

## Configuration

### Docker Compose Location
`/opt/termix/docker-compose.yml`

### Environment Variables
Created in `/opt/termix/.env` (if needed):
```env
# Termix configuration
TERMIX_PORT=8080
# Add any custom env vars as needed
```

### Data Persistence
All Termix data is stored in `/opt/termix/data`:
- **Database**: Encrypted SQLite with server credentials
- **SSH Keys**: Generated and managed by Termix
- **User Settings**: RBAC, 2FA settings, preferences

## Features & Usage

### SSH Terminal
- Full-featured web terminal with split-screen (up to 4 panels)
- Tab-based interface for multiple sessions
- Copy/paste support
- Session reconnection

### SSH Tunneling
- Create local and remote tunnels
- Automatic reconnection with health monitoring
- Persistent tunnel configuration

### File Management
- Upload/download files via web interface
- Remote file editing with syntax highlighting
- View code and media files directly
- Directory navigation and operations

### Docker Management
- List containers across connected servers
- Start/stop/pause/remove containers
- Exec into containers with web terminal
- View container logs and stats

### Server Monitoring
- Real-time CPU, memory, disk, network usage
- Server uptime tracking
- Firewall status visibility
- Custom dashboards with network graphs

### Host Management
- Save SSH connections with tags and folders
- Automated SSH key deployment
- Organize servers by environment, project, or location
- Quick connect from saved hosts

### Security Features
- **RBAC**: Role-based access control for multi-user
- **2FA**: TOTP authentication support
- **OIDC**: Single sign-on integration
- **Encryption**: All credentials encrypted in database

## Initial Setup

### First Login
1. Navigate to https://termix.manticorum.com
2. Create admin account on first run
3. **Important**: Enable 2FA immediately after account creation

### Add Your First Server
1. Click "Add Host" or "+"
2. Enter connection details:
   - **Hostname**: Server IP or hostname (e.g., `10.10.0.33`)
   - **Port**: 22 (default SSH)
   - **Username**: SSH user (e.g., `cal` or `root`)
   - **Auth**: SSH key (recommended) or password
3. Test connection
4. Organize with tags (e.g., `proxmox`, `docker`, `production`)

### Deploy SSH Keys
Termix can generate and deploy SSH keys to your servers:
1. Generate key pair in Termix
2. Use "Deploy SSH Key" feature
3. Termix will add the key to `~/.ssh/authorized_keys` on target server

### Organize Servers
Create folders for organization:
- **By Environment**: `production/`, `development/`, `homelab/`
- **By Function**: `docker-hosts/`, `databases/`, `proxmox/`
- **By Location**: `local/`, `cloud/`

## Quick Import: All Home Lab Servers

A pre-configured JSON import file is available with all your home lab servers:

**File**: `server-configs/termix/homelab-hosts-import.json`

### Import Instructions
1. Log into Termix at https://termix.manticorum.com
2. Go to **Settings** → **Import/Export**
3. Click **Import Hosts**
4. Upload `homelab-hosts-import.json`
5. All 12 servers will be imported with:
   - Organized folders (Infrastructure, LXC Containers, VMs, Cloud)
   - Appropriate tags for filtering
   - Docker management enabled for Docker hosts
   - File manager with correct default paths
   - System monitoring enabled
   - Database tunnel pre-configured for strat-database

### After Import: Configure SSH Keys
The import uses SSH key authentication. After importing:
1. Go to each host in Termix
2. Edit host settings
3. Add your SSH private key or generate a new one in Termix
4. Use Termix's "Deploy SSH Key" feature to add keys to servers

**Or** use password authentication temporarily:
- Edit each host and change `authType` to "password"
- Add password in the password field
- Later switch to SSH keys for security

### Included Servers

| Server | IP | User | Folder | Features |
|--------|-----|------|--------|----------|
| proxmox | 10.10.0.11 | root | Infrastructure | ⭐ Pinned, Monitoring |
| ubuntu-manticore | 10.10.0.226 | cal | Physical Servers | ⭐ Pinned, Docker, Media |
| n8n | 10.10.0.210 | root | LXC Containers | ⭐ Pinned, Docker, Automation |
| discord-bots | 10.10.0.33 | cal | Virtual Machines | Docker, Dev Bots |
| sba-bots | 10.10.0.88 | cal | Virtual Machines | ⭐ Pinned, Docker, Production |
| strat-database | 10.10.0.42 | cal | Virtual Machines | Docker, Database, Tunnel |
| arr-stack | 10.10.0.221 | root | LXC Containers | Docker, Media Automation |
| foundry-lxc | 10.10.0.223 | root | LXC Containers | Docker, Gaming |
| openclaw | 10.10.0.224 | root | LXC Containers | Docker, AI Assistant |
| gitea | 10.10.0.225 | root | LXC Containers | Git Server, CI/CD |
| home-assistant | 10.0.0.28 | root | Virtual Machines | Smart Home |
| akamai | 172.237.147.99 | root | Cloud Servers | Docker, Public Cloud |

## Backup

### What to Backup
1. **Termix database**: `/opt/termix/data/` (contains all settings, credentials, SSH keys)
2. **Docker compose**: `/opt/termix/docker-compose.yml`
3. **Environment**: `/opt/termix/.env` (if exists)

### Backup Commands
```bash
# Full data directory (includes encrypted database)
tar -czf termix-backup-$(date +%Y%m%d).tar.gz /opt/termix

# Database only
cp /opt/termix/data/termix.db /backups/termix-db-$(date +%Y%m%d).db
```

### Restore
```bash
# Stop Termix
cd /opt/termix
docker compose down

# Restore data
tar -xzf termix-backup.tar.gz -C /

# Start Termix
docker compose up -d
```

## Upgrades

### Update Termix
```bash
cd /opt/termix

# Pull latest image
docker compose pull

# Restart with new image
docker compose down
docker compose up -d

# Check logs for successful start
docker compose logs -f
```

### Check Version
View version in Termix web UI: Settings → About

## Integration with NPM

Configure reverse proxy on NPM (10.10.0.16):
- **Domain**: termix.manticorum.com
- **Scheme**: http
- **Forward Hostname/IP**: 10.10.0.210
- **Forward Port**: 8180
- **SSL**: Let's Encrypt
- **Websockets**: ✅ **MUST BE ENABLED** (required for terminal sessions)
- **Block Common Exploits**: Enabled
- **Cache Assets**: Disabled (for real-time terminal)

## Troubleshooting

### Container won't start
```bash
# Check logs
docker compose logs

# Common issues:
# - Port 8080 already in use
# - Missing /opt/termix/data directory
# - Permissions on data directory
```

### Can't connect to servers from Termix
```bash
# Ensure Termix container has network access
docker exec -it termix ping 10.10.0.11

# Check SSH from container
docker exec -it termix ssh -v user@server-ip

# Verify firewall rules on target servers
```

### 502 Bad Gateway on web
```bash
# Check Termix is running and listening
docker compose ps
docker compose logs

# Test local connection
curl http://localhost:8080

# Verify NPM can reach container
curl http://10.10.0.226:8080
```

### Terminal sessions disconnect
- Ensure websockets are enabled in NPM
- Check for network connectivity issues
- Verify Termix auto-reconnect settings

### Database corruption
```bash
# Stop Termix
docker compose down

# Restore from backup
cp /backups/termix-db-YYYYMMDD.db /opt/termix/data/termix.db

# Start Termix
docker compose up -d
```

## Security Notes

- All credentials are encrypted in SQLite database
- SSH keys are stored securely within Termix
- Enable 2FA for all users
- Use SSH key authentication instead of passwords where possible
- LXC is unprivileged for better isolation
- Termix only accessible via HTTPS through NPM
- Consider restricting NPM access to internal network only

## Advanced Configuration

### OIDC Integration
For single sign-on with external identity provider:
1. Configure OIDC provider (e.g., Authelia, Keycloak)
2. Add OIDC settings to Termix via environment variables
3. Enable OIDC login in Termix settings

### Custom Themes
Termix uses Tailwind/Shadcn UI. Themes can be customized if building from source.

### Multi-User Setup
1. Create user accounts in Termix admin panel
2. Assign roles (Admin, User, Viewer)
3. Set per-user server access permissions
4. Enforce 2FA for all users

## Related Documentation

- [Official Termix GitHub](https://github.com/Termix-SSH/Termix)
- [Termix Documentation](https://github.com/Termix-SSH/Termix/wiki) (check for wiki)
- [Proxmox LXC Config](../proxmox/lxc/226.conf)
- [Networking Setup](../../networking/CONTEXT.md)

## Deployment Date

**Created**: 2026-02-03
**By**: Claude Code (Proxmox Skill)
**Tech**: Termix (Docker) on Ubuntu 22.04 LXC

## Next Steps

After deployment:
1. ✅ Create LXC 226 on Proxmox
2. ✅ Install Docker and Docker Compose
3. ✅ Deploy Termix via docker-compose
4. ⬜ Configure NPM reverse proxy
5. ⬜ Set up first admin account
6. ⬜ Enable 2FA
7. ⬜ Add home lab servers to Termix
8. ⬜ Deploy SSH keys to managed servers
9. ⬜ Organize servers with tags and folders
10. ⬜ Test terminal, file management, Docker control features