Added readme
All checks were successful
Deploy Apartment Dashboard / deploy (push) Successful in 10m0s
All checks were successful
Deploy Apartment Dashboard / deploy (push) Successful in 10m0s
This commit is contained in:
306
apartment-dashboard-readme.md
Normal file
306
apartment-dashboard-readme.md
Normal file
@ -0,0 +1,306 @@
|
||||
# 🏠 Country Club Towers & Gardens - Apartment Dashboard
|
||||
|
||||
A real-time React dashboard for monitoring apartment availability, pricing trends, and market analytics at Country Club Towers & Gardens.
|
||||
|
||||
## 🚀 Live Dashboard
|
||||
|
||||
**URL:** https://apartments.maverickapplications.com
|
||||
|
||||
## 📋 Features
|
||||
|
||||
### 📊 Overview Dashboard
|
||||
- **Real-time metrics**: Available units, new units today, rented units, turnover rate
|
||||
- **Price trend charts**: 15-day moving average with area charts
|
||||
- **Unit availability tracking**: Visual representation of market supply
|
||||
- **Floor plan distribution**: Pie chart showing unit types by plan
|
||||
- **Recent activity feed**: New units, rentals, and price changes
|
||||
|
||||
### 🏠 Available Units View
|
||||
- **Interactive unit cards** with detailed information
|
||||
- **Priority highlighting** for Maroon Peak units (< $3,800)
|
||||
- **Filtering options** by floor plan and bedroom count
|
||||
- **Price range visualization** showing current price position
|
||||
- **Detailed unit modal** with price history charts
|
||||
|
||||
### 📈 Market Analytics
|
||||
- **Price distribution** by floor plan
|
||||
- **Market insights** with actionable recommendations
|
||||
- **Trend analysis** and activity indicators
|
||||
|
||||
## 🛠️ Technology Stack
|
||||
|
||||
- **Frontend**: React 18 + Vite
|
||||
- **Styling**: Tailwind CSS
|
||||
- **Charts**: Recharts
|
||||
- **Icons**: Lucide React
|
||||
- **Deployment**: Docker + Nginx
|
||||
- **CI/CD**: Gitea Actions
|
||||
- **Reverse Proxy**: Traefik with SSL
|
||||
|
||||
## 🔄 Development Workflow
|
||||
|
||||
### Local Development
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://git.maverickapplications.com/stephen/apartment-dashboard.git
|
||||
cd apartment-dashboard
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start development server
|
||||
npm run dev
|
||||
# App will be available at http://localhost:5173
|
||||
|
||||
# Build for production
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
1. **Create a new branch** (optional but recommended):
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
2. **Make your changes** and test locally
|
||||
|
||||
3. **Commit and push**:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Description of your changes"
|
||||
git push origin main # or your branch name
|
||||
```
|
||||
|
||||
4. **Automatic deployment**: The Gitea Actions workflow will automatically:
|
||||
- Build the React app
|
||||
- Create a Docker image
|
||||
- Deploy to production
|
||||
- Make it available at https://apartments.maverickapplications.com
|
||||
|
||||
## 🚀 Deployment Architecture
|
||||
|
||||
### Current Setup
|
||||
- **Source**: Gitea repository (`git.maverickapplications.com`)
|
||||
- **CI/CD**: Gitea Actions with Act runner
|
||||
- **Container**: Docker with Nginx serving built React app
|
||||
- **Routing**: Traefik reverse proxy with automatic SSL
|
||||
- **Domain**: `apartments.maverickapplications.com`
|
||||
|
||||
### File Locations
|
||||
- **Source code**: Git repository only
|
||||
- **Running app**: Docker container (`apartment-dashboard`)
|
||||
- **Built files**: Inside container at `/usr/share/nginx/html`
|
||||
- **Docker Compose**: Exists only during CI/CD deployment (not persisted on host)
|
||||
- **Management**: Use direct Docker commands or redeploy via Gitea Actions
|
||||
|
||||
### Auto-restart Behavior
|
||||
✅ **The app will automatically restart** after server reboots due to `restart: unless-stopped` in docker-compose.yml
|
||||
|
||||
## 🔧 Operational Commands
|
||||
|
||||
### Check App Status
|
||||
```bash
|
||||
# Check if container is running
|
||||
docker ps | grep apartment-dashboard
|
||||
|
||||
# View container logs
|
||||
docker logs apartment-dashboard
|
||||
|
||||
# Check detailed container info
|
||||
docker inspect apartment-dashboard
|
||||
```
|
||||
|
||||
### Manual Control
|
||||
|
||||
**Note**: Since the app is deployed via CI/CD, there's no persistent docker-compose.yml on the host filesystem. Use Docker commands directly:
|
||||
|
||||
```bash
|
||||
# Stop the app
|
||||
docker stop apartment-dashboard
|
||||
docker rm apartment-dashboard
|
||||
|
||||
# Restart the app (redeploy)
|
||||
# Push a new commit to trigger redeployment, or manually trigger workflow in Gitea Actions
|
||||
|
||||
# Restart existing container
|
||||
docker restart apartment-dashboard
|
||||
|
||||
# View logs in real-time
|
||||
docker logs -f apartment-dashboard
|
||||
|
||||
# Quick restart without rebuild
|
||||
docker restart apartment-dashboard
|
||||
```
|
||||
|
||||
**For full redeployment**: Go to Gitea Actions tab and manually trigger the workflow, or push a new commit.
|
||||
|
||||
### Troubleshooting
|
||||
```bash
|
||||
# Check Traefik routing
|
||||
curl -I https://apartments.maverickapplications.com
|
||||
|
||||
# Check if Traefik sees the service
|
||||
# Visit: https://traefik.maverickapplications.com
|
||||
|
||||
# Test container directly (bypass Traefik)
|
||||
docker exec apartment-dashboard curl -I http://localhost:80
|
||||
|
||||
# Check container filesystem
|
||||
docker exec apartment-dashboard ls -la /usr/share/nginx/html
|
||||
```
|
||||
|
||||
## 🔄 CI/CD Pipeline
|
||||
|
||||
The deployment pipeline is fully automated through Gitea Actions:
|
||||
|
||||
### Workflow Trigger
|
||||
- **Push to main branch** → Automatic deployment
|
||||
- **Manual trigger** → Available in Actions tab
|
||||
|
||||
### Pipeline Steps
|
||||
1. **Checkout code** from Gitea
|
||||
2. **Setup Node.js** environment
|
||||
3. **Install dependencies** (`npm ci`)
|
||||
4. **Build React app** (`npm run build`)
|
||||
5. **Build Docker image** with Nginx
|
||||
6. **Deploy to server** and start container
|
||||
7. **Verify deployment** is successful
|
||||
|
||||
### Workflow File
|
||||
`.github/workflows/deploy.yml` - Contains the complete deployment pipeline
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
apartment-dashboard/
|
||||
├── src/
|
||||
│ ├── App.jsx # Main dashboard component
|
||||
│ ├── index.css # Global styles + Tailwind
|
||||
│ └── main.jsx # React entry point
|
||||
├── public/ # Static assets
|
||||
├── .github/workflows/
|
||||
│ └── deploy.yml # Gitea Actions workflow
|
||||
├── docker-compose.yml # Container orchestration
|
||||
├── Dockerfile # Multi-stage build config
|
||||
├── nginx.conf # Nginx configuration
|
||||
├── package.json # Dependencies and scripts
|
||||
├── tailwind.config.js # Tailwind CSS configuration
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🔐 Security & Performance
|
||||
|
||||
### Security Features
|
||||
- **SSL/TLS**: Automatic Let's Encrypt certificates via Traefik
|
||||
- **Security headers**: Configured in Nginx
|
||||
- **Network isolation**: Container runs in Traefik network only
|
||||
|
||||
### Performance Optimizations
|
||||
- **Multi-stage Docker build**: Minimal production image
|
||||
- **Nginx caching**: Static assets cached for 1 year
|
||||
- **Gzip compression**: Enabled for all text assets
|
||||
- **Production build**: Optimized React bundle
|
||||
|
||||
## 🔄 Integration with Apartment Scraper
|
||||
|
||||
### Current Status
|
||||
The dashboard displays **mock data** that matches your MongoDB structure:
|
||||
- Daily summaries (new units, rented units, turnover rates)
|
||||
- Unit details (pricing, floor plans, availability)
|
||||
- Price history and trends
|
||||
- Market analytics
|
||||
|
||||
### Next Steps for Live Data
|
||||
To connect real data from your apartment scraper:
|
||||
|
||||
1. **Create API backend** (Express.js + MongoDB)
|
||||
2. **Add API endpoints**:
|
||||
- `GET /api/daily-summary`
|
||||
- `GET /api/price-history`
|
||||
- `GET /api/available-units`
|
||||
- `GET /api/recent-activity`
|
||||
3. **Update React app** to fetch from API instead of mock data
|
||||
4. **Deploy API backend** through same CI/CD pipeline
|
||||
|
||||
## 📊 Data Structure
|
||||
|
||||
The dashboard expects data in this format (matching your MongoDB collections):
|
||||
|
||||
### Daily Summary
|
||||
```javascript
|
||||
{
|
||||
date: "2025-01-15",
|
||||
newUnits: 3,
|
||||
rentedUnits: 5,
|
||||
staleUnits: 1,
|
||||
netChange: -3,
|
||||
turnoverRate: 8.2,
|
||||
totalAvailable: 47
|
||||
}
|
||||
```
|
||||
|
||||
### Available Units
|
||||
```javascript
|
||||
{
|
||||
unitCode: "W2506",
|
||||
planName: "Maroon Peak",
|
||||
bedCount: 2,
|
||||
bathCount: 2,
|
||||
area: 1089,
|
||||
currentPrice: 3750,
|
||||
minPrice: 3650,
|
||||
maxPrice: 3850,
|
||||
daysAvailable: 12,
|
||||
community: "Country Club Towers"
|
||||
}
|
||||
```
|
||||
|
||||
## 🚨 Emergency Procedures
|
||||
|
||||
### If App is Down
|
||||
1. **Check container status**: `docker ps | grep apartment-dashboard`
|
||||
2. **View logs**: `docker logs apartment-dashboard`
|
||||
3. **Quick restart**: `docker restart apartment-dashboard`
|
||||
4. **Full redeploy**: Push new commit or manually trigger Gitea Actions workflow
|
||||
5. **Check Traefik**: Visit traefik dashboard
|
||||
|
||||
### If Server Reboots
|
||||
✅ **No action needed** - Container will auto-restart
|
||||
|
||||
### If Domain Not Accessible
|
||||
1. **Check DNS**: `nslookup apartments.maverickapplications.com`
|
||||
2. **Check Traefik**: Visit `https://traefik.maverickapplications.com`
|
||||
3. **Check container**: `docker ps | grep apartment-dashboard`
|
||||
4. **Check logs**: `docker logs traefik`
|
||||
|
||||
## 📞 Support Information
|
||||
|
||||
### Related Infrastructure
|
||||
- **Main infrastructure**: `/media/stephen/Storage_Linux/infrastructure/`
|
||||
- **Traefik dashboard**: https://traefik.maverickapplications.com
|
||||
- **Gitea repository**: https://git.maverickapplications.com
|
||||
- **Harbor registry**: https://registry.maverickapplications.com
|
||||
|
||||
### Useful Links
|
||||
- **Apartment scraper cron jobs**: Located on server
|
||||
- **Email reporting**: `run_email_report.sh`
|
||||
- **Data collection**: `run_scraper.sh`
|
||||
|
||||
## 📝 Version History
|
||||
|
||||
- **v1.0**: Initial dashboard with mock data
|
||||
- **Future**: API integration for live apartment data
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Create feature branch
|
||||
2. Make changes
|
||||
3. Test locally with `npm run dev`
|
||||
4. Push to repository
|
||||
5. Gitea Actions will automatically deploy
|
||||
|
||||
**Dashboard URL**: https://apartments.maverickapplications.com
|
||||
Reference in New Issue
Block a user