feat: 🚀 Initialize TSYS Developer Support Stack demo environment
- Add comprehensive Docker Compose configuration with 16 developer services - Configure Homepage dashboard with service discovery and grouping - Set up environment configuration for demo deployment - Include project documentation (PRD, README, User Guide, Agent guidelines) - Establish foundation for developer tooling stack with proper networking and security Services include developer tools (Homepage, Atuin, Wakapi, ArchiveBox, Tube Archivist, MailHog), infrastructure (PostgreSQL, Elasticsearch, Redis, Docker Socket Proxy), monitoring (InfluxDB, Grafana), and documentation (Draw.io, Kroki).
This commit is contained in:
TSYSDevStack Team
263
SupportStack/demo/USER_GUIDE.md
Normal file
263
SupportStack/demo/USER_GUIDE.md
Normal file
@@ -0,0 +1,263 @@
|
||||
# 🚀 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! 🚀
|
||||
Reference in New Issue
Block a user