sojorn/sojorn_docs/directus/directus.md

# Directus CMS Implementation

## Overview
Directus CMS is installed and configured for the Sojorn project, providing a headless CMS for content management.

## Access Information
- **URL**: `https://cms.sojorn.net`
- **Admin Interface**: `https://cms.sojorn.net/admin`
- **API Endpoint**: `https://cms.sojorn.net`

## Server Configuration

### Nginx Configuration
The CMS is served via nginx with SSL encryption:

```nginx
server {
    listen 80;
    server_name cms.sojorn.net;
    return 301 https://cms.sojorn.net;
}

server {
    listen 443 ssl;
    server_name cms.sojorn.net;
    
    ssl_certificate /etc/letsencrypt/live/cms.sojorn.net/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cms.sojorn.net/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    
    location / {
        proxy_pass http://localhost:8055;
    }
}
```

### SSL Certificate
- **Type**: Let's Encrypt (auto-renewing)
- **Domains**: cms.sojorn.net
- **Expiry**: 2026-05-06 (89 days from install)
- **Renewal**: Automatic via certbot

## Directus Configuration

### Environment Variables
```bash
KEY='sj_auth_key_replace_me_securely'
DB_CLIENT='pg'
DB_HOST='127.0.0.1'
DB_PORT='5432'
DB_DATABASE='postgres'
DB_USER='postgres'
DB_PASSWORD='A24Zr7AEoch4eO0N'
ADMIN_EMAIL='admin@sojorn.com'
PUBLIC_URL='https://cms.sojorn.net'
```

### Database Connection
- **Type**: PostgreSQL
- **Host**: localhost (127.0.0.1)
- **Port**: 5432
- **Database**: postgres
- **User**: postgres
- **Password**: A24Zr7AEoch4eO0N

### Service Management
Directus runs as a background process using npx:

```bash
cd ~/directus
KEY='sj_auth_key_replace_me_securely' \
DB_CLIENT='pg' \
DB_HOST='127.0.0.1' \
DB_PORT='5432' \
DB_DATABASE='postgres' \
DB_USER='postgres' \
DB_PASSWORD='A24Zr7AEoch4eO0N' \
ADMIN_EMAIL='admin@sojorn.com' \
PUBLIC_URL='https://cms.sojorn.net' \
npx directus start &
```

### Port Information
- **Internal Port**: 8055
- **External Access**: Via nginx proxy on 443 (HTTPS)
- **Process**: Runs as user `patrick`

## Administration

### Initial Setup
1. Visit `https://cms.sojorn.net/admin`
2. Use email: `admin@sojorn.com`
3. Set initial password during first login

### Process Management Commands

#### Check if Directus is running
```bash
ps aux | grep directus | grep -v grep
```

#### Check port status
```bash
sudo netstat -tlnp | grep 8055
```

#### Start Directus
```bash
cd ~/directus
KEY='sj_auth_key_replace_me_securely' DB_CLIENT='pg' DB_HOST='127.0.0.1' DB_PORT='5432' DB_DATABASE='postgres' DB_USER='postgres' DB_PASSWORD='A24Zr7AEoch4eO0N' ADMIN_EMAIL='admin@sojorn.com' PUBLIC_URL='https://cms.sojorn.net' npx directus start &
```

#### Stop Directus
```bash
pkill -f directus
```

#### Restart Directus
```bash
pkill -f directus
cd ~/directus
KEY='sj_auth_key_replace_me_securely' DB_CLIENT='pg' DB_HOST='127.0.0.1' DB_PORT='5432' DB_DATABASE='postgres' DB_USER='postgres' DB_PASSWORD='A24Zr7AEoch4eO0N' ADMIN_EMAIL='admin@sojorn.com' PUBLIC_URL='https://cms.sojorn.net' npx directus start &
```

## File Locations

### Directus Installation
- **Directory**: `/home/patrick/directus/`
- **Configuration**: Environment variables (no .env file)
- **Logs**: Console output (no dedicated log file)

### Nginx Configuration
- **Config File**: `/etc/nginx/sites-available/cms.conf`
- **Enabled**: `/etc/nginx/sites-enabled/cms.conf`
- **SSL Certs**: `/etc/letsencrypt/live/cms.sojorn.net/`

### SSL Certificates
- **Full Chain**: `/etc/letsencrypt/live/cms.sojorn.net/fullchain.pem`
- **Private Key**: `/etc/letsencrypt/live/cms.sojorn.net/privkey.pem`

## Troubleshooting

### Common Issues

#### 502 Bad Gateway
- **Cause**: Directus not running
- **Fix**: Start Directus service using the start command above

#### Connection Refused
- **Cause**: Port 8055 not accessible
- **Fix**: Check if Directus is running and restart if needed

#### SSL Certificate Issues
- **Cause**: Certificate expired or misconfigured
- **Fix**: Check certbot status and renew if needed

### Log Locations
- **Nginx Error Log**: `/var/log/nginx/error.log`
- **Nginx Access Log**: `/var/log/nginx/access.log`
- **Directus Logs**: Console output only

## Maintenance

### SSL Certificate Renewal
Certificates auto-renew via certbot. To check status:
```bash
sudo certbot certificates
```

### Database Backups
Ensure regular PostgreSQL backups are configured for the `postgres` database.

### Updates
Directus shows update notifications in the console. To update:
```bash
cd ~/directus
npm update directus
```

## Security Notes

### Important
- The `KEY` should be replaced with a secure, randomly generated string for production
- The `SECRET` environment variable should be set for production to persist tokens
- Database credentials are stored in environment variables - consider using a .env file for better security

### Recommended Improvements
1. Set a secure `SECRET` environment variable
2. Replace the default `KEY` with a cryptographically secure string
3. Configure proper logging rotation
4. Set up monitoring for the Directus process
5. Implement database backup strategy

## API Usage

Once configured, the Directus API is available at:
- **REST API**: `https://cms.sojorn.net`
- **GraphQL**: `https://cms.sojorn.net/graphql`
- **Admin**: `https://cms.sojorn.net/admin`

## Integration Notes

The Directus instance is configured to work with the existing Sojorn PostgreSQL database, allowing direct access to application data for content management purposes.