Skip to main content

Installation Guide

This guide will walk you through setting up the FeelyFeely CDN from scratch.

Prerequisites​

System Requirements​

  • Python: 3.11.9 (specified in runtime.txt)
  • Operating System: Linux/macOS/Windows (Linux recommended for production)
  • Memory: Minimum 2GB RAM (4GB+ recommended for production)
  • Storage: 10GB+ available space

Required Services​

  • MySQL Database (for application data)
  • MongoDB Instance (for document storage)
  • DigitalOcean Spaces (for file storage)
  • Uploadcare Account (for image processing)
  • Keycloak Server (for authentication)

Installation Steps​

1. Clone the Repository​

git clone https://github.com/FeelyFeely/ff-cdn.git
cd ff-cdn

2. Set Up Python Environment​

# Create virtual environment
python3.11 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate

3. Install System Dependencies​

Ubuntu/Debian​

sudo apt-get update
sudo apt-get install -y curl python3-opencv imagemagick libsm6 libxext6 libpq-dev

CentOS/RHEL​

sudo yum install -y curl opencv-python ImageMagick libSM libXext postgresql-devel

macOS​

brew install imagemagick opencv postgresql

4. Install Python Dependencies​

pip install -r requirements.txt

5. Database Setup​

MySQL Setup​

-- Create databases
CREATE DATABASE main;
CREATE DATABASE business;

-- Create users
CREATE USER 'orc8r'@'%' IDENTIFIED BY 'your_password';
CREATE USER 'bzns'@'%' IDENTIFIED BY 'your_password';

-- Grant permissions
GRANT ALL PRIVILEGES ON main.* TO 'orc8r'@'%';
GRANT ALL PRIVILEGES ON business.* TO 'bzns'@'%';
FLUSH PRIVILEGES;

MongoDB Setup​

# Install MongoDB (Ubuntu example)
wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org

# Start MongoDB
sudo systemctl start mongod
sudo systemctl enable mongod

6. DigitalOcean Spaces Configuration​

  1. Create Spaces Buckets:

    • ff.user.assets
    • ff.organization.assets
    • ff.mobiledevice.photos
    • ff.vehicle.photos

  2. Generate API Keys:

    • Go to DigitalOcean API section
    • Create Spaces access keys for each bucket
    • Note down the keys and secrets

7. Uploadcare Setup​

  1. Create Uploadcare Account: Visit uploadcare.com
  2. Get API Keys: Navigate to Dashboard → API Keys
  3. Note Public and Secret Keys

8. Environment Configuration​

Create and configure your .env file:

cp .env.example .env

Edit .env with your actual credentials:

# Main Database
MYSQL_HOST=your-mysql-host
MYSQL_USER=orc8r
MYSQL_PASSWORD=your-mysql-password
MYSQL_DB=main
MYSQL_CURSORCLASS=DictCursor
MYSQL_PORT=3306

# Business Database
MYSQL_BIZ_HOST=your-mysql-host
MYSQL_BIZ_USER=bzns
MYSQL_BIZ_PASSWORD=your-biz-password
MYSQL_BIZ_DB=business
MYSQL_BIZ_CURSORCLASS=DictCursor
MYSQL_BIZ_PORT=3306

# SQLAlchemy Bridge
MYSQL_MAIN_BRIDGE=mysql+pymysql://orc8r:password@host:3306/main
MYSQL_BIZ_BRIDGE=mysql+pymysql://bzns:password@host:3306/business

# MongoDB
MONGODB_MAIN_PROD=mongodb://username:password@host:27017/gateway

# Keycloak
KC_URL=https://your-keycloak-instance/
KC_REALM=feelyfeely
KC_CLIENT_ID=web
KC_SECRET=your-keycloak-secret
[email protected]
KC_ADMIN_PASS=your-admin-password

# DigitalOcean Spaces - User Assets
DO_USER_ASSET_SPACES_REGION=fra1
DO_USER_ASSET_SPACES_KEY=your-spaces-key
DO_USER_ASSET_SPACES_SECRET=your-spaces-secret
DO_USER_ASSET_SPACES_BUCKET_NAME=ff.user.assets

# DigitalOcean Spaces - Organization Assets
DO_ORG_ASSET_SPACES_REGION=fra1
DO_ORG_ASSET_SPACES_KEY=your-org-spaces-key
DO_ORG_ASSET_SPACES_SECRET=your-org-spaces-secret
DO_ORG_ASSET_SPACES_BUCKET_NAME=ff.organization.assets

# DigitalOcean Spaces - Mobile Device Photos
DO_MOBILE_DEVICE_PHOTO_SPACES_REGION=fra1
DO_MOBILE_DEVICE_PHOTO_SPACES_KEY=your-mobile-key
DO_MOBILE_DEVICE_PHOTO_SPACES_SECRET=your-mobile-secret
DO_MOBILE_DEVICE_PHOTO_SPACES_BUCKET_NAME=ff.mobiledevice.photos

# DigitalOcean Spaces - Vehicle Photos
DO_VEHICLE_PHOTO_SPACES_REGION=fra1
DO_VEHICLE_PHOTO_SPACES_KEY=your-vehicle-key
DO_VEHICLE_PHOTO_SPACES_SECRET=your-vehicle-secret
DO_VEHICLE_PHOTO_SPACES_BUCKET_NAME=ff.vehicle.photos

# Uploadcare
UPLOAD_CARE_PUBLIC_KEY=your-public-key
UPLOAD_CARE_SECRET_KEY=your-secret-key

# Paystack (if using payment features)
PAYSTACK_SECRET=your-paystack-secret

9. Asset Setup​

Create required directories and watermark assets:

# Create asset directory
mkdir -p assets

# Add your watermark files
# Place watermark.png in the assets directory

10. SSL Certificates​

For MongoDB SSL connection, ensure you have the certificate file:

# The repository includes mongodb-1-cert.crt
# Verify it's in the root directory
ls -la mongodb-1-cert.crt

Verification​

1. Test Database Connections​

python -c "
from db_config import mysql
from dbutils.mongodb import MongoDB

print('Testing MySQL connection...')
try:
    cursor = mysql.connection.cursor()
    cursor.execute('SELECT 1')
    print('MySQL: ✓ Connected')
except Exception as e:
    print(f'MySQL: ✗ Error - {e}')

print('Testing MongoDB connection...')
try:
    mongo = MongoDB()
    print('MongoDB: ✓ Connected')
except Exception as e:
    print(f'MongoDB: ✗ Error - {e}')
"

2. Test Uploadcare Integration​

python -c "
from models.image.uploadcare.uploadcare_client import UploadcareClient

try:
    upc = UploadcareClient()
    print('Uploadcare: ✓ Connected')
except Exception as e:
    print(f'Uploadcare: ✗ Error - {e}')
"

3. Test DigitalOcean Spaces​

python -c "
from models.digitalocean.spaces import DigitalOceanSpaces
from decouple import config

try:
    spaces = DigitalOceanSpaces(
        region=config('DO_USER_ASSET_SPACES_REGION'),
        endpoint=f'https://{config(\"DO_USER_ASSET_SPACES_REGION\")}.digitaloceanspaces.com',
        access_key=config('DO_USER_ASSET_SPACES_KEY'),
        secret_key=config('DO_USER_ASSET_SPACES_SECRET')
    )
    print('DigitalOcean Spaces: ✓ Connected')
except Exception as e:
    print(f'DigitalOcean Spaces: ✗ Error - {e}')
"

Running the Application​

Development Mode​

python server.py

Production Mode​

gunicorn --config gunicorn_config.py wsgi:app

Using Docker​

# Build the image
docker build -t ff-cdn .

# Run the container
docker run -p 8080:8080 --env-file .env ff-cdn

Troubleshooting​

Common Issues​

  1. Import Errors

    # Ensure virtual environment is activated
    source venv/bin/activate
    pip install -r requirements.txt

  2. Database Connection Errors

    • Verify database credentials in .env
    • Check database server is running
    • Confirm firewall settings allow connections

  3. Missing System Dependencies

    # Install OpenCV system dependencies
    sudo apt-get install python3-opencv libsm6 libxext6

  4. SSL Certificate Issues

    • Ensure mongodb-1-cert.crt is in the root directory
    • Check MongoDB SSL configuration

Log Files​

Check application logs for detailed error information:

# Application logs
tail -f logs/app.log

# Gunicorn logs (in production)
tail -f logs/gunicorn.log

Support​

If you encounter issues during installation:

  • Check the troubleshooting section above
  • Review log files for error details
  • Contact support at [email protected]
  • Create an issue on the GitHub repository