Self Hosting Guide

Introduction

This guide provides comprehensive instructions for deploying Citadel in self-hosted environments using Docker Compose. Follow these steps to set up your own secure, enterprise-grade social media management platform.

Prerequisites

Before beginning the self-hosting process, ensure you have the following:

• Docker Engine 20.10 or higher
• Docker Compose 1.29 or higher
• At least 4 GB RAM and 2 CPU cores
• Domain name (recommended for production)

Quick Start

Follow these steps to quickly deploy Citadel in a self-hosted environment:

1. Clone the Repository

git clone https://github.com/naviNBRuas/citadel-dashboard.git
cd citadel-dashboard

2. Create Environment File

cp .env.production.example .env.production

3. Edit Environment File

nano .env.production

4. Start the Services

docker-compose --env-file .env.production up -d

Environment Configuration

Required Variables

These environment variables must be configured for proper operation:

• DB_PASSWORD: Secure password for the database
• VAULT_TOKEN: Secure token for HashiCorp Vault
• JWT_SECRET: Strong secret for JWT token signing
• ENTERPRISE_LICENSE_TOKEN: License token for enterprise features (if applicable)
• LICENSE_JWT_SECRET: Secret for license server JWT tokens (if using enterprise features)

Optional Variables

These variables enhance functionality but are not required:

• ACME_EMAIL: Email for Let's Encrypt SSL certificates
• OAuth credentials for Google/GitHub login

Security Considerations

Credential Protection

• Database Credentials: Database password is stored in environment variables and is not exposed to external networks
• Vault Security: Vault token is stored securely in environment variables with data persisted in a Docker volume
• JWT Security: JWT secrets are stored in environment variables with short token expiration times
• Social Media Credentials: Stored encrypted in Vault and never in plain text

Network Security

• Internal Network: Services communicate through a private Docker network with only necessary ports exposed
• External Access: Traefik reverse proxy provides HTTPS termination and automatic SSL certificates

Data Protection

• Encryption at Rest: Database data is stored in encrypted volumes with Vault encrypting all stored credentials
• Encryption in Transit: All external communication uses HTTPS with secured internal service communication

Deployment Options

Production Deployment

For production use, ensure you:

• Use a domain name with proper DNS configuration
• Configure SSL certificates (Traefik handles this automatically)
• Set strong passwords and secrets
• Regularly backup your data
• Monitor logs and security events

Development Deployment

For development/testing:

# Use the default development environment
docker-compose up -d

Custom Deployment

You can customize the deployment by:

• Modifying the docker-compose.yml file
• Adjusting environment variables
• Adding additional services or networks

Backup and Recovery

Database Backup

# Backup database
docker-compose exec postgres pg_dump -U citadel citadel_prod > backup.sql

# Restore database
docker-compose exec -T postgres psql -U citadel citadel_prod < backup.sql

Vault Backup

Vault data is stored in the vault_data volume. Regularly backup this volume:

# Backup Vault data
docker run --rm -v citadel-dashboard_vault_data:/data -v $(pwd):/backup alpine tar czf /backup/vault-backup.tar.gz -C /data .

Monitoring and Maintenance

Health Checks

All services include health checks. Monitor service status with:

docker-compose ps

Logs

View logs for troubleshooting:

# View all logs
docker-compose logs

# View specific service logs
docker-compose logs citadel-core

Updates

To update to the latest version:

git pull
docker-compose down
docker-compose up -d --build

Troubleshooting

Common Issues

• Port Conflicts: Ensure ports 80, 443, 5432, 6379, 8200 are available
• Permission Errors: Ensure Docker has proper permissions
• Health Check Failures: Check service logs for errors

Getting Help

• Check the logs: docker-compose logs
• Review environment variables
• Ensure all required variables are set
• Check service dependencies

Enterprise Features

To use enterprise features:

1. Obtain an enterprise license token
2. Set ENTERPRISE_LICENSE_TOKEN in your environment
3. Deploy the license server (included in the compose file)
4. Configure the license server with proper credentials

Enterprise features include:

• Advanced analytics and reporting
• Audit logging
• Single Sign-On (SSO)
• Custom integrations
• Brand monitoring
• Competitor analysis