blogging-cms/INSTALL-COOLIFY.md

Blogging CMS - Coolify Installation Guide

Deploy your self-hosted blogging platform on Coolify in minutes.

Prerequisites

• Active Coolify instance (v4.0+)
• Git repository (GitHub, GitLab, Gitea)
• Domain name (optional, but recommended)
• 1GB RAM minimum

Step 1: Prepare Your Repository

1. Fork or clone this repository to your Git provider

   git clone https://github.com/kalvin0x8d0/blogging-cms.git
   cd blogging-cms
   

2. Push to your Git provider (if using your own fork)

   git remote add origin <your-git-repo-url>
   git push -u origin main
   

Step 2: Create Coolify Project

1. Log into your Coolify dashboard
2. Click "New Project"
3. Select "Docker Compose" as the project type
4. Name your project (e.g., "My Blog")

Step 3: Connect Your Git Repository

1. Click "New Service"
2. Select "Git Repository"
3. Choose your Git provider (GitHub/GitLab/Gitea)
4. Select this repository
5. Leave the path as . (root directory)
6. Click "Save"

Step 4: Configure Environment Variables

In Coolify's environment editor, add:

# Database
DB_HOST=mariadb
DB_PORT=3306
DB_USER=cms_user
DB_PASSWORD=generate_secure_password_here
DB_ROOT_PASSWORD=generate_root_password_here
DB_NAME=blogging_cms

# Application
PORT=8080
SITE_URL=https://yourdomain.com
SESSION_KEY=generate_secure_random_key_here

# Optional
MARKDOWN_BREAKS=true
MARKDOWN_TYPOGRAPHER=false

Generating Secure Keys

# Generate SESSION_KEY (on your local machine)
openssl rand -base64 32

# Or use this Python one-liner
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Step 5: Configure Reverse Proxy (Caddy)

1. In Coolify, go to "Network" or "Proxy" settings
2. Click "New Reverse Proxy"
3. Set Domain: yourdomain.com
4. Set Target: http://localhost:8080 (or container name)
5. Enable HTTPS: Yes (auto-certificate with Let's Encrypt)
6. Save

Step 6: Deploy

1. Click "Deploy" in your project
2. Monitor logs:

   docker-compose logs -f
   

3. Wait for MariaDB to initialize (30-60 seconds)

Step 7: Access Your Blog

• Homepage: https://yourdomain.com
• Dashboard: https://yourdomain.com/dashboard
• RSS Feed: https://yourdomain.com/feed

Post-Deployment

1. First-Time Setup

# Access Coolify terminal
docker-compose exec app sh

# Check database connection
go run main.go

2. Create Admin User

# Via API (POST request)
curl -X POST https://yourdomain.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "you@example.com",
    "password": "secure_password"
  }'

3. Backup Strategy

Enable automated backups in Coolify:

1. Storage Settings → Add Volume Backup
2. Select: mariadb_data
3. Frequency: Daily or Weekly
4. Retention: 30 days

4. Domain Configuration

If using DNS, add:

blog.example.com  CNAME  your-coolify-domain.com

Troubleshooting

Container Won't Start

Check logs:

docker-compose logs app
docker-compose logs mariadb

Common issues:

• Port 8080 already in use → Change PORT in environment
• MariaDB not ready → Wait 1-2 minutes, redeploy
• Database password error → Verify all DB_* variables match

Posts Not Showing

1. Verify database is running:

   docker-compose exec mariadb mysql -u cms_user -p blogging_cms -e "SHOW TABLES;"
   

2. Check if posts are published:

   SELECT title, published FROM posts LIMIT 5;
   

Static Files Return 404

• Ensure /static directory exists
• Check file permissions in Docker: ls -la static/
• Verify paths in main.go match your setup

HTTPS Certificate Issues

1. Let's Encrypt renewal:

   docker-compose down
   docker-compose up -d
   

2. Manual certificate:

   • Use Coolify's built-in cert manager
   • Or configure in reverse proxy settings

Monitoring & Maintenance

Health Checks

Coolify monitors the / endpoint. If unhealthy:

curl https://yourdomain.com/

Database Maintenance

Weekly optimization:

docker-compose exec mariadb mysql -u cms_user -p blogging_cms \
  -e "OPTIMIZE TABLE posts, users, comments;"

Log Rotation

Coolify handles log rotation automatically. Check:

• Application logs: Docker logs
• Access logs: Reverse proxy logs

Performance Optimization

For Coolify

1. Enable Docker layer caching

   • Coolify → Project Settings → Docker

2. Set appropriate resource limits

   • mariadb: 256MB RAM
   • app: 128MB RAM

3. Enable persistent volumes

   • Database data
   • Static assets cache

Application Settings

Add to environment:

# Connection pooling
DB_MAX_CONNECTIONS=20

# Cache headers
CACHE_POSTS=3600

Updating the Application

1. Pull latest changes:

   git pull origin main
   git push origin main
   

2. Coolify auto-redeployment (if enabled)

   • Or manually trigger deploy

3. Database migrations:

   • Usually automatic on startup
   • Check logs for any errors

Backup & Restore

Automatic Backups

Coolify has built-in volume backup:

1. Storage → Volumes → mariadb_data
2. Set backup schedule
3. Retention policy: 30 days

Manual Backup

docker-compose exec mariadb mysqldump \
  -u cms_user -p blogging_cms > backup.sql

Restore

docker-compose exec mariadb mysql \
  -u cms_user -p blogging_cms < backup.sql

Security Checklist

• ✅ Change all default passwords
• ✅ Enable HTTPS via Let's Encrypt
• ✅ Set strong SESSION_KEY
• ✅ Enable database backups
• ✅ Configure firewall rules
• ✅ Monitor access logs
• ✅ Keep Coolify updated

Getting Help

• Issues: GitHub Issues (if public repo)
• Coolify Docs: docs.coollabs.io
• Docker Help: docs.docker.com

---

Your self-hosted blog is ready! 🎉

Start writing at https://yourdomain.com/dashboard ✍️