chore: Add Nixpacks configuration and deployment guide

- Nixpacks.toml for auto-detection build
- Complete deployment documentation for Easypanel
- Environment variables setup
- Database persistence instructions
- Troubleshooting guide

Optimized for Nixpacks deployment (no Dockerfile needed).
This commit is contained in:
Kunthawat
2026-03-10 13:16:15 +07:00
parent 305e2bd217
commit 30aeb0f418

View File

@@ -0,0 +1,272 @@
# 🚀 Easypanel Deployment Guide (Nixpacks)
## Overview
This Astro website is configured for **automatic deployment on Easypanel** using **Nixpacks**.
---
## ✅ Auto-Detection
Easypanel will automatically detect this as a Node.js project and use Nixpacks to build it.
**No Dockerfile required!**
---
## 📋 Configuration
### Easypanel Settings:
1. **Project Name:** `dealplustech-astro`
2. **Service Name:** `dealplustech-website`
3. **Build Type:** `Nixpacks` (auto-detected)
4. **Source:** Git repository
5. **Branch:** `main`
6. **Port:** `4321` (or use `$PORT` env variable)
7. **Auto-Deploy:** ✅ Enabled
---
## 🔐 Environment Variables
Set these in Easypanel → Settings → Environment:
```bash
# Database (SQLite file - Nixpacks will persist this)
ASTRO_DB_REMOTE_URL=file:/data/consent.db
# Admin Dashboard
ADMIN_PASSWORD=your-secure-password-here
# Umami Analytics (optional)
PUBLIC_UMAMI_WEBSITE_ID=your-website-id
PUBLIC_UMAMI_DOMAIN=https://analytics.moreminimore.com
# Site URL
PUBLIC_SITE_URL=https://your-domain.com
```
**⚠️ IMPORTANT:** Change `ADMIN_PASSWORD` from the default!
---
## 🗄️ Database Persistence
The consent logging database needs persistent storage.
### Option A: Volume Mount (Recommended)
1. In Easypanel, go to Service → Volumes
2. Add a new volume:
- **Path:** `/data`
- **Size:** `1 GB` (minimum)
3. Set environment variable:
```bash
ASTRO_DB_REMOTE_URL=file:/data/consent.db
```
### Option B: Turso (Production)
For managed database:
1. Create account at https://turso.tech
2. Create database
3. Get connection URL
4. Set environment:
```bash
ASTRO_DB_REMOTE_URL=libsql://your-db.turso.io
ASTRO_DB_APP_TOKEN=your-token
```
---
## 🔄 Deployment Workflow
### Automatic (Git Push):
1. **Make changes locally**
```bash
# Edit files
npm run build # Test locally
git add .
git commit -m "Update content"
git push origin main
```
2. **Easypanel auto-deploys:**
- Detects push to `main`
- Runs Nixpacks build
- Deploys new version
- Health checks pass
- Traffic switches
3. **Verify:**
- Check Easypanel dashboard
- Visit website URL
- Test cookie consent
### Manual (Force Deploy):
1. Go to Service in Easypanel
2. Click "Deploy"
3. Select latest commit
4. Deploy
---
## 📊 Monitoring
### Health Check
Nixpacks will automatically health check the service.
**Endpoint:** `http://localhost:4321/`
**Expected:** Status 200 OK
### Logs
View in Easypanel:
- Service → Logs
- Real-time deployment logs
- Runtime logs
### Metrics
Easypanel provides:
- CPU usage
- Memory usage
- Network traffic
- Request count
---
## 🔐 Security Checklist
- [ ] Change `ADMIN_PASSWORD` from default
- [ ] Enable HTTPS (Easypanel provides SSL automatically)
- [ ] Set up firewall rules (if needed)
- [ ] Configure database persistence
- [ ] Regular backups of consent logs
---
## 🐛 Troubleshooting
### Build Fails
**Check:**
1. `npm run build` works locally
2. `package.json` scripts are correct
3. All dependencies installed
4. Node version is 20.x
**Fix:**
```bash
npm install
npm run build
git push origin main
```
### Database Errors
**Check:**
1. Volume is mounted at `/data`
2. Environment variable `ASTRO_DB_REMOTE_URL` is set
3. Database file has write permissions
**Fix:**
```bash
# In Easypanel:
# 1. Add volume at /data
# 2. Set ASTRO_DB_REMOTE_URL=file:/data/consent.db
# 3. Redeploy
```
### Cookie Consent Not Working
**Check:**
1. CookieConsentBanner component is imported
2. BASE_LAYOUT includes the component
3. No console errors
**Fix:**
```bash
# Verify component is included in layout
# Check browser console for errors
# Clear cache and reload
```
### Admin Dashboard 404
**Check:**
1. Route is `/admin/consent-logs`
2. Service is running
3. No build errors
**Fix:**
```bash
# Access: https://your-domain.com/admin/consent-logs
# Login with ADMIN_PASSWORD
# Check server logs for errors
```
---
## 📈 Performance Optimization
### Recommended Resources:
- **CPU:** `0.5` core (minimum)
- **Memory:** `512 MB` (minimum)
- **Disk:** `1 GB` for database
### Caching:
Nixpacks automatically caches:
- `node_modules/`
- Build output
### CDN (Optional):
For better performance, add Cloudflare:
1. Point DNS to Easypanel
2. Enable Cloudflare proxy
3. Configure caching rules
---
## 📞 Support
**Documentation:**
- Astro: https://docs.astro.build
- Nixpacks: https://nixpacks.com
- Easypanel: https://easypanel.io/docs
**Admin Dashboard:**
- URL: `/admin/consent-logs`
- Password: Set via `ADMIN_PASSWORD` env
**Contact:**
- Email: info@dealplustech.co.th
- LINE: @dealplustech
---
## ✅ Post-Deployment Checklist
- [ ] Website loads correctly
- [ ] Cookie consent appears on first visit
- [ ] Consent is logged to database
- [ ] Admin dashboard accessible
- [ ] Umami Analytics loading (if configured)
- [ ] All pages working
- [ ] Mobile responsive
- [ ] HTTPS enabled (automatic with Easypanel)
- [ ] Database backed up regularly
---
**Last Updated:** 2026-03-10
**Version:** 1.0.0
**Deployment:** Nixpacks on Easypanel