TSYSDevStack/SupportStack/demo/USER_GUIDE.md

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

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

# 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 (smtplib)
import smtplib
server = smtplib.SMTP('192.168.3.6', 1025)
server.sendmail(from_addr, to_addr, message)

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

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:

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

   docker ps | grep tsysdevstack-supportstack
   

2. Check service logs:

   docker logs tsysdevstack-supportstack-service-name
   

3. Verify port accessibility:

   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:

# 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! 🚀