How-To Guide
Development Workflow
From idea to production: the complete development cycle for your installation.
Standard workflow
The development cycle for most changes:
Start local development
cd website/
./atelier.sh devMake changes
Edit files, add components, update content. Hot reload shows changes immediately.
# Edit a page
vim src/pages/index.astro
# Add a component
cp src/components/Example.astro src/components/NewFeature.astro
# Update styles
vim src/styles/globals.cssTest locally
Verify changes at http://localhost:4321. Check browser console for errors.
Commit changes
git add .
git commit -m "Add new feature component"
git push origin mainDeploy to production
# SSH to server
ssh user@server.com
# Pull latest code and deploy
cd /opt/installations/your-installation/website
./deploy-prod.shHot reload best practices
Hot module reload (HMR) speeds development. Tips for effective use:
What triggers reload:
- • Changes to
.astrofiles → full page reload - • Changes to
.tsx/.jsxfiles → React Fast Refresh - • Changes to
.cssfiles → injected without reload - • Changes to
astro.config.mjs→ requires manual restart
When HMR doesn't work:
- • Check
ENABLE_HMR=truein.env - • Verify volume mounts in
docker-compose.dev.yml - • Clear browser cache (Ctrl+Shift+R / Cmd+Shift+R)
- • Restart containers:
./atelier.sh dev
Testing changes
Before committing, verify:
1. Build succeeds
# Stop dev server
./atelier.sh stop
# Test production build
npm run build
# Expected:
# ✓ Built in X ms2. No console errors
Open browser DevTools (F12) → Console. Fix any errors or warnings.
3. Responsive design
Test at different viewport sizes: Mobile (375px), Tablet (768px), Desktop (1280px)
DevTools → Toggle device toolbar (Ctrl+Shift+M / Cmd+Option+M)
4. Links work
Click through navigation, verify all internal links resolve
Commit guidelines
Write clear, actionable commit messages:
Good commit messages:
git commit -m "Add testimonial component to homepage"
git commit -m "Fix navigation menu mobile layout"
git commit -m "Update deployment guide with Caddy setup"
git commit -m "Remove unused HandDrawn variants"Avoid:
git commit -m "updates" # Too vague
git commit -m "WIP" # What was in progress?
git commit -m "fix bug" # Which bug? Pattern: [Action] [What] [Where/Why] - "Add dark mode toggle to settings"
Pre-deployment checklist
Before deploying to production:
- Production build succeeds (
npm run build) - No console errors in browser
- Responsive at 375px, 768px, 1280px
- All navigation links work
- Environment variables updated in
.env.production - Changes committed to git
- Deployment script tested (
./deploy-prod.sh)
Post-deployment verification
After deploying, verify production:
# Test HTTPS works
curl -I https://your-domain.com
# Check for errors in logs
docker compose logs --tail=100
# Verify certificate
openssl s_client -connect your-domain.com:443 -servername your-domain.com < /dev/null
# Test page load time
curl -o /dev/null -s -w "%{time_total}\n" https://your-domain.comMonitor for 10 minutes after deployment. Check logs for errors, test key functionality.
Quick reference
| Task | Command |
|---|---|
| Start development | ./atelier.sh dev |
| Stop development | ./atelier.sh stop |
| View logs | ./atelier.sh logs |
| Clean rebuild | ./atelier.sh clean && ./atelier.sh dev |
| Test build | npm run build |
| Deploy production | ./deploy-prod.sh |
