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**
   ```bash
   git clone https://github.com/kalvin0x8d0/blogging-cms.git
   cd blogging-cms
   ```

2. **Push to your Git provider** (if using your own fork)
   ```bash
   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:

```env
# 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

```bash
# 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

```bash
# Access Coolify terminal
docker-compose exec app sh

# Check database connection
go run main.go
```

### 2. Create Admin User

```bash
# 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:
```dns
blog.example.com  CNAME  your-coolify-domain.com
```

## Troubleshooting

### Container Won't Start

**Check logs:**
```bash
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:
   ```bash
   docker-compose exec mariadb mysql -u cms_user -p blogging_cms -e "SHOW TABLES;"
   ```

2. Check if posts are published:
   ```bash
   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**:
   ```bash
   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:

```bash
curl https://yourdomain.com/
```

### Database Maintenance

**Weekly optimization:**
```bash
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:
```env
# Connection pooling
DB_MAX_CONNECTIONS=20

# Cache headers
CACHE_POSTS=3600
```

## Updating the Application

1. **Pull latest changes**:
   ```bash
   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

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

### Restore

```bash
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` ✍️