# 🚀 TSYS Developer Support Stack - User Guide

## 📖 Quick Start for Developers

Welcome to the TSYS Developer Support Stack! This guide will help you get up and running with all the developer tools in minutes.

### 🎯 Access Your Dashboard

**Main Dashboard:** http://192.168.3.6:4000

This is your central hub for accessing all services. The dashboard automatically discovers and displays all available services.

---

## 🛠️ Available Services

### 🏠 Homepage Dashboard
**URL:** http://192.168.3.6:4000

Your personalized developer dashboard featuring:
- **Service Discovery:** Automatically detects all running services
- **Resource Monitoring:** Real-time CPU, memory, and disk usage
- **Quick Search:** Integrated search functionality
- **Customizable Layout:** Arrange widgets to your preference

### 📚 Atuin - Shell History
**URL:** http://192.168.3.6:4001

Never lose a command again! Atuin provides:
- **Synced Shell History:** Access your command history across machines
- **Powerful Search:** Find commands instantly with advanced search
- **Statistics:** Track your shell usage patterns
- **Encryption:** Secure storage of your command history

**Quick Setup:**
```bash
# Install Atuin client
curl --proto '=https' --tlsv1.2 -sSf https://setup.atuin.sh | sh

# Configure to use your server
atuin register
atuin import bash
```

### ⏱️ Wakapi - Time Tracking
**URL:** http://192.168.3.6:4002

Track your coding time automatically:
- **Language Detection:** Automatically detects programming languages
- **Project Tracking:** Organize time by projects
- **Detailed Reports:** View productivity trends and statistics
- **API Access:** Integrate with other tools

**Setup with your favorite editor:**
- **VS Code:** Install the WakaTime extension
- **Vim/Neovim:** Use the wakatime-vim plugin
- **JetBrains:** Install the WakaTime plugin

### 🗄️ ArchiveBox - Web Archiving
**URL:** http://192.168.3.6:4003

Save web pages permanently:
- **Complete Archives:** Saves HTML, CSS, JS, PDFs, and media
- **Full-Text Search:** Search across all archived content
- **Tag Organization:** Organize archives with tags and folders
- **Scheduled Archiving:** Automatically archive websites on schedules

**Quick Usage:**
```bash
# Archive a single URL
echo "https://example.com" | archivebox add

# Archive multiple URLs from a file
cat urls.txt | archivebox add
```

### 📺 Tube Archivist - YouTube Media Library
**URL:** http://192.168.3.6:4004

Your personal YouTube archive:
- **Channel/Playlist Backup:** Download entire channels or playlists
- **Metadata Management:** Rich metadata including descriptions, thumbnails
- **Subtitles:** Download and index subtitles for searchability
- **Streaming:** Stream your archived videos directly from the interface

**Getting Started:**
1. Visit the web interface
2. Add YouTube channels or playlists you want to archive
3. Set up download schedules
4. Enjoy your personal media library!

### 📧 MailHog - Email Testing
**URL:** http://192.168.3.6:4005
**SMTP Port:** 1025

Perfect for email development and testing:
- **Email Capture:** Captures all emails sent to port 1025
- **Web Interface:** View captured emails in a clean web interface
- **HTML/Plain Text:** View both HTML and plain text versions
- **Release Function:** Release emails to real SMTP servers for testing

**Configuration for Development:**
```python
# Python (smtplib)
import smtplib
server = smtplib.SMTP('192.168.3.6', 1025)
server.sendmail(from_addr, to_addr, message)
```

```javascript
// Node.js (nodemailer)
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransporter({
  host: '192.168.3.6',
  port: 1025
});
```

---

## 🔧 Advanced Configuration

### Customizing Homepage

Edit the configuration files in the `homepage/config/` directory:

**`settings.yaml`** - Main dashboard settings
**`docker.yaml`** - Docker integration settings  
**`bookmarks.yaml`** - Your quick links

### Adding New Services

1. Add your service to `docker-compose.yml`
2. Add Homepage labels for automatic discovery:
```yaml
labels:
  - "homepage.group=My Services"
  - "homepage.name=My Service"
  - "homepage.icon=your-icon"
  - "homepage.description=Service description"
```

### Environment Variables

Key environment variables you might want to customize:

```bash
# Database credentials
POSTGRES_USER=atuin
POSTGRES_PASSWORD=your_secure_password

# Atuin settings
ATUIN_HOST=http://192.168.3.6:4001

# Wakapi settings  
WAKAPI_PASSWORD_SALT=your_custom_salt
```

---

## 🔍 Troubleshooting

### Service Not Accessible

1. **Check if service is running:**
   ```bash
   docker ps | grep tsysdevstack-supportstack
   ```

2. **Check service logs:**
   ```bash
   docker logs tsysdevstack-supportstack-service-name
   ```

3. **Verify port accessibility:**
   ```bash
   curl -I http://192.168.3.6:port-number
   ```

### High Resource Usage

Some services are resource-intensive:
- **Elasticsearch** (Tube Archivist): ~780MB RAM, high CPU during startup
- **Tube Archivist**: ~145MB RAM, high CPU during video processing

**Optimization Tips:**
- Restart services that are consuming excessive resources
- Consider limiting Tube Archivist concurrent downloads
- Monitor Elasticsearch heap size if needed

### Data Persistence

All data is stored in Docker volumes:
- PostgreSQL data: Shell history and user data
- Wakapi data: Time tracking data  
- ArchiveBox data: Web archives and metadata
- Tube Archivist data: Videos and metadata

**Backup Important Data:**
```bash
# List volumes
docker volume ls | grep tsysdevstack

# Backup a volume
docker run --rm -v volume_name:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz /data
```

---

## 📊 Performance Tips

### Resource Usage Summary

| Service | Typical RAM Usage | CPU Usage | Notes |
|---------|------------------|-----------|-------|
| Homepage | ~100MB | Minimal | Lightweight dashboard |
| Atuin | ~6MB | Minimal | Shell history service |
| Wakapi | ~30MB | Minimal | Time tracking |
| MailHog | ~7MB | Minimal | Email testing |
| PostgreSQL | ~70MB | Low | Database backend |
| ArchiveBox | ~107MB | Low | Web archiving |
| Docker Socket Proxy | ~20MB | Minimal | Service discovery |
| Elasticsearch | ~780MB | High (startup) | Search engine |
| Tube Archivist | ~145MB | High (processing) | Media processing |

### Optimization Recommendations

1. **For Development:** All services run comfortably on a modern laptop
2. **For Production:** Consider dedicated resources for Elasticsearch and Tube Archivist
3. **Resource Monitoring:** Use the Homepage resource widgets to monitor usage

---

## 🔗 Quick Links

- **Main Dashboard:** http://192.168.3.6:4000
- **Shell History:** http://192.168.3.6:4001  
- **Time Tracking:** http://192.168.3.6:4002
- **Web Archive:** http://192.168.3.6:4003
- **Media Library:** http://192.168.3.6:4004
- **Email Testing:** http://192.168.3.6:4005

---

## 🆘 Need Help?

1. **Check the main README.md** for technical details
2. **Run the test suite:** `./test-stack.sh`
3. **Check service logs:** `docker compose logs service-name`
4. **Verify all services:** `docker compose ps`

---

## 🎉 Best Practices

- **Use the Homepage dashboard** as your primary entry point
- **Set up Atuin on all your development machines** for synced shell history
- **Configure Wakapi with your code editor** for automatic time tracking
- **Archive important documentation** with ArchiveBox for future reference
- **Use MailHog for all development email testing** to avoid spam
- **Monitor resource usage** via the Homepage widgets

Happy developing! 🚀