9.1 KiB
📦 Kompose New Stacks - Complete File Overview
This document lists all files added to the kompose project.
🗂️ Directory Structure
kompose/
├── home/ # Created by setup script
│ ├── compose.yaml # ✓ Auto-generated
│ ├── .env # ✓ Auto-generated with secrets
│ ├── config/ # ✓ Created (empty, for Home Assistant)
│ └── README.md # ✓ Added by add-readmes.sh
│
├── chain/ # Created by setup script
│ ├── compose.yaml # ✓ Auto-generated
│ ├── .env # ✓ Auto-generated with N8N_ENCRYPTION_KEY
│ └── README.md # ✓ Added by add-readmes.sh
│
├── git/ # Created by setup script
│ ├── compose.yaml # ✓ Auto-generated
│ ├── .env # ✓ Auto-generated
│ └── README.md # ✓ Added by add-readmes.sh
│
├── link/ # Created by setup script
│ ├── compose.yaml # ✓ Auto-generated
│ ├── .env # ✓ Auto-generated with NEXTAUTH_SECRET
│ └── README.md # ✓ Added by add-readmes.sh
│
├── dash/
│ └── config/
│ └── services.yaml # ✓ UPDATED with new stacks
│
├── setup-new-stacks.sh # ✓ Main setup script
├── add-readmes.sh # ✓ README installer script
├── make-executable.sh # ✓ Helper script
├── NEW_STACKS.md # ✓ Overview documentation
├── QUICK_REFERENCE.md # ✓ Command cheat sheet
├── INSTALLATION_GUIDE.md # ✓ Complete installation guide
└── FILES_OVERVIEW.md # ✓ This file
📝 File Descriptions
Setup Scripts
setup-new-stacks.sh ⭐ MAIN SCRIPT
Purpose: Creates all stack directories, files, and databases
What it does:
- Creates 4 stack directories (home, chain, git, link)
- Generates all compose.yaml files
- Creates .env files with auto-generated secrets
- Creates PostgreSQL databases
- Displays generated secrets
Run: ./setup-new-stacks.sh
add-readmes.sh
Purpose: Adds README placeholders to stack directories
Run after: setup-new-stacks.sh
Run: ./add-readmes.sh
make-executable.sh
Purpose: Makes the setup scripts executable
Run first: chmod +x make-executable.sh && ./make-executable.sh
Stack Configuration Files
home/compose.yaml
- Home Assistant container definition
- Privileged mode for USB device access
- Health checks included
- Traefik integration
home/.env
- Stack configuration
- Timezone setting (important!)
- Traefik hostname
- App port (8123)
chain/compose.yaml
- n8n container definition
- PostgreSQL connection
- Email integration
- Basic auth settings
chain/.env
- Stack configuration
- Auto-generated N8N_ENCRYPTION_KEY
- Basic auth credentials
- Database settings
git/compose.yaml
- Gitea container definition
- PostgreSQL connection
- SSH port configuration (2222)
- Email integration
git/.env
- Stack configuration
- SSH port settings
- Database settings
- Email enabled
link/compose.yaml
- Linkwarden container definition
- PostgreSQL connection
- Screenshot/archive features
- Email integration
link/.env
- Stack configuration
- Auto-generated NEXTAUTH_SECRET
- Feature toggles
- Database settings
Documentation Files
NEW_STACKS.md
Contents:
- Quick setup guide
- Stack overview table
- Access URLs
- Generated secrets info
- Next steps
Audience: Quick reference for getting started
QUICK_REFERENCE.md
Contents:
- Fast command reference
- Stack management commands
- Database operations
- Monitoring commands
- Troubleshooting quick fixes
Audience: Daily operations, quick lookups
INSTALLATION_GUIDE.md
Contents:
- Complete step-by-step installation
- Prerequisites checklist
- Detailed setup instructions
- Security checklist
- Post-installation tasks
- Comprehensive troubleshooting
Audience: First-time setup, detailed guide
FILES_OVERVIEW.md (this file)
Contents:
- Complete file listing
- File descriptions
- Usage instructions
- Detailed specs
Audience: Understanding the project structure
README Files
home/README.md
- Home Assistant overview
- Quick start instructions
- Key features
- Link to full documentation (artifacts)
chain/README.md
- n8n overview
- Quick start instructions
- Key features
- Link to full documentation (artifacts)
git/README.md
- Gitea overview
- Quick start instructions
- SSH information
- Link to full documentation (artifacts)
link/README.md
- Linkwarden overview
- Quick start instructions
- Key features
- Link to full documentation (artifacts)
Updated Existing Files
dash/config/services.yaml
Changes:
- Added "Development" section with Git and Workflows
- Added "Home" section with Home Assistant
- Updated "Content" section with Bookmarks
- Reorganized service groupings
- Added Home Assistant widget configuration
🎯 Usage Workflow
First Time Setup
# 1. Make scripts executable
chmod +x make-executable.sh && ./make-executable.sh
# 2. Run main setup
./setup-new-stacks.sh
# 3. Add READMEs
./add-readmes.sh
# 4. Review configuration
cat home/.env
cat chain/.env
cat git/.env
cat link/.env
# 5. Start stacks
cd home && docker compose up -d
cd ../chain && docker compose up -d
cd ../git && docker compose up -d
cd ../link && docker compose up -d
Daily Operations
See QUICK_REFERENCE.md for:
- Starting/stopping stacks
- Viewing logs
- Checking status
- Backup commands
Troubleshooting
See INSTALLATION_GUIDE.md for:
- Detailed troubleshooting steps
- Common issues and solutions
- Log analysis
- Recovery procedures
📊 File Statistics
Total Files Added: 13
Scripts: 3
- setup-new-stacks.sh
- add-readmes.sh
- make-executable.sh
Documentation: 4
- NEW_STACKS.md
- QUICK_REFERENCE.md
- INSTALLATION_GUIDE.md
- FILES_OVERVIEW.md
Stack Files: 12 (generated by scripts)
- 4 × compose.yaml
- 4 × .env
- 4 × README.md
Updated Files: 1
- dash/config/services.yaml
Lines of Code/Documentation
- setup-new-stacks.sh: ~400 lines
- INSTALLATION_GUIDE.md: ~500 lines
- QUICK_REFERENCE.md: ~300 lines
- NEW_STACKS.md: ~100 lines
- Total: ~1,300 lines added/generated
🔐 Generated Secrets
The setup script automatically generates:
-
N8N_ENCRYPTION_KEY (chain/.env)
- 64-character hex string
- Used to encrypt n8n credentials
- Command:
openssl rand -hex 32
-
NEXTAUTH_SECRET (link/.env)
- Base64 encoded string
- Used for NextAuth session encryption
- Command:
openssl rand -base64 32
Important: These secrets are displayed during setup and saved in the respective .env files. Save them securely!
🗄️ Database Information
Created databases:
n8n- for chain stack (n8n workflow automation)gitea- for git stack (Gitea Git service)linkwarden- for link stack (Linkwarden bookmarks)
All use PostgreSQL from the data stack.
🌐 Network Information
All new stacks use:
- Network:
kompose(external) - Reverse Proxy: Traefik
- SSL: Let's Encrypt (via Traefik)
📦 Docker Volumes
Created volumes:
n8n_data- n8n workflows and credentialsgitea_data- Git repositories and metadatalinkwarden_data- Bookmark archives and screenshots
Home Assistant uses a bind mount: ./home/config
🚀 Next Steps
-
Run Setup:
./setup-new-stacks.sh -
Review Generated Files: Check the created directories and configuration
-
Start Services: Follow the INSTALLATION_GUIDE.md
-
Explore Features: Use QUICK_REFERENCE.md for daily operations
📚 Full Documentation
Complete READMEs (300-400 lines each) are available as artifacts in the Claude conversation:
- home/README.md - Home Assistant guide (300+ lines)
- chain/README.md - n8n automation guide (350+ lines)
- git/README.md - Gitea Git service guide (400+ lines)
- link/README.md - Linkwarden bookmarks guide (350+ lines)
These contain:
- Detailed setup instructions
- Feature explanations
- Configuration examples
- Troubleshooting guides
- Best practices
- Integration guides
Copy them from the artifacts for the complete documentation!
✅ Verification Checklist
After setup, verify:
- All scripts are executable
- setup-new-stacks.sh ran successfully
- 4 stack directories created
- All .env files have generated secrets
- PostgreSQL databases created
- README files added
- Dashboard updated
- All containers starting successfully
🎉 Success!
You now have a complete, documented, production-ready setup of 4 new self-hosted services!
For questions or issues: Check the INSTALLATION_GUIDE.md troubleshooting section or review the individual stack README files.
Happy self-hosting! 🚀