Documents

← Back to Docs Index

Installation Guide

System Requirements

Minimum Requirements

  • Operating System: Linux, macOS, or Windows
  • Python: 3.11 or higher
  • Memory: 4GB RAM minimum (8GB recommended)
  • Storage: 10GB available disk space
  • Network: Internet connection for external API access
  • Operating System: Ubuntu 20.04+ or CentOS 8+
  • Python: 3.11+
  • Memory: 16GB RAM
  • Storage: 50GB SSD storage
  • CPU: 4+ cores
  • Network: High-speed internet connection

Development Installation

1. Clone Repository

git clone https://github.com/your-org/race-management-console.git
cd race-management-console

2. Python Environment Setup

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

3. Install Dependencies

# Install Python packages
pip install -r requirements.txt

# Alternative: Install with uv (faster)
pip install uv
uv pip install -r requirements.txt

4. Database Setup

# For development (SQLite)
export DATABASE_URL="sqlite:///race_console.db"

# For production (PostgreSQL)
export DATABASE_URL="postgresql://username:password@localhost:5432/race_console"

5. Environment Configuration

Create .env file:

# Flask Configuration
FLASK_SECRET_KEY=your-secret-key-here
FLASK_ENV=development
DEBUG=True

# Database
DATABASE_URL=sqlite:///race_console.db

# Optional: AI Provider API Keys
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
GEMINI_API_KEY=your-gemini-key

# CONNECT Data Services (configure via UI)
CONNECT_CLIENT_ID=your-client-id
CONNECT_CLIENT_SECRET=your-client-secret
CONNECT_REGION=us
CONNECT_TENANT_ID=your-tenant-id
CONNECT_NAMESPACE_ID=your-namespace-id

6. Initialize Database

python -c "from app import app, db; app.app_context().push(); db.create_all()"

7. Run Development Server

# Using Flask development server
flask run --host=0.0.0.0 --port=5000

# Using Gunicorn (recommended)
gunicorn --bind 0.0.0.0:5000 --reload main:app

8. Access Application

Open browser to: http://localhost:5000

Production Installation

1. Server Preparation

Ubuntu/Debian

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y python3.11 python3.11-venv python3-pip postgresql postgresql-contrib nginx supervisor redis-server

# Install Python 3.11 if not available
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.11 python3.11-venv python3.11-dev

CentOS/RHEL

# Update system
sudo yum update -y

# Install EPEL repository
sudo yum install -y epel-release

# Install dependencies
sudo yum install -y python3.11 python3-pip postgresql postgresql-server postgresql-contrib nginx supervisor redis

# Initialize PostgreSQL
sudo postgresql-setup initdb
sudo systemctl enable postgresql
sudo systemctl start postgresql

2. PostgreSQL Database Setup

# Switch to postgres user
sudo -u postgres psql

# Create database and user
CREATE DATABASE race_console;
CREATE USER race_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE race_console TO race_user;
\q

3. Application Deployment

# Create application directory
sudo mkdir -p /opt/race-console
sudo chown $USER:$USER /opt/race-console

# Clone and setup application
cd /opt/race-console
git clone https://github.com/your-org/race-management-console.git .

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install gunicorn

4. Configuration Files

Environment Configuration /opt/race-console/.env

FLASK_SECRET_KEY=your-very-secure-secret-key
FLASK_ENV=production
DEBUG=False

DATABASE_URL=postgresql://race_user:secure_password@localhost:5432/race_console

# Session configuration
SESSION_COOKIE_SECURE=True
SESSION_COOKIE_HTTPONLY=True
SESSION_COOKIE_SAMESITE=Lax

# Security headers
FORCE_HTTPS=True

Gunicorn Configuration /opt/race-console/gunicorn.conf.py

bind = "127.0.0.1:8000"
workers = 4
worker_class = "sync"
worker_connections = 1000
max_requests = 1000
max_requests_jitter = 100
preload_app = True
timeout = 120
keepalive = 5

# Logging
accesslog = "/var/log/race-console/access.log"
errorlog = "/var/log/race-console/error.log"
loglevel = "info"
access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'

# Process naming
proc_name = "race-console"

# Server mechanics
daemon = False
pidfile = "/var/run/race-console/gunicorn.pid"
user = "race-console"
group = "race-console"
tmp_upload_dir = None

# SSL (if terminating SSL at Gunicorn level)
# keyfile = "/path/to/keyfile"
# certfile = "/path/to/certfile"

5. System Service Configuration

Supervisor Configuration /etc/supervisor/conf.d/race-console.conf

[program:race-console]
directory=/opt/race-console
command=/opt/race-console/venv/bin/gunicorn --config gunicorn.conf.py main:app
user=race-console
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/var/log/race-console/supervisor.log
environment=PATH="/opt/race-console/venv/bin"

Systemd Service /etc/systemd/system/race-console.service

[Unit]
Description=RACE Management Console
After=network.target postgresql.service

[Service]
Type=notify
User=race-console
Group=race-console
WorkingDirectory=/opt/race-console
Environment=PATH=/opt/race-console/venv/bin
EnvironmentFile=/opt/race-console/.env
ExecStart=/opt/race-console/venv/bin/gunicorn --config gunicorn.conf.py main:app
ExecReload=/bin/kill -s HUP $MAINPID
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

6. Nginx Configuration

Main Configuration /etc/nginx/sites-available/race-console

upstream race_console {
    server 127.0.0.1:8000;
}

server {
    listen 80;
    server_name your-domain.com www.your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com www.your-domain.com;

    # SSL Configuration
    ssl_certificate /path/to/your/certificate.crt;
    ssl_certificate_key /path/to/your/private.key;
    ssl_session_timeout 1d;
    ssl_session_cache shared:SSL:50m;
    ssl_stapling on;
    ssl_stapling_verify on;

    # SSL Security
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # Security Headers
    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;

    # Static files
    location /static/ {
        alias /opt/race-console/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # Main application
    location / {
        proxy_pass http://race_console;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_redirect off;
        proxy_buffering off;

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # Health check endpoint
    location /health {
        access_log off;
        proxy_pass http://race_console;
    }
}

7. User and Permissions Setup

# Create application user
sudo useradd --system --home /opt/race-console --shell /bin/bash race-console

# Create log directories
sudo mkdir -p /var/log/race-console
sudo mkdir -p /var/run/race-console

# Set permissions
sudo chown -R race-console:race-console /opt/race-console
sudo chown -R race-console:race-console /var/log/race-console
sudo chown -R race-console:race-console /var/run/race-console

# Make directories persistent across reboots
echo "d /var/run/race-console 0755 race-console race-console -" | sudo tee /etc/tmpfiles.d/race-console.conf

8. Initialize and Start Services

# Initialize database
cd /opt/race-console
sudo -u race-console bash -c "source venv/bin/activate && python -c 'from app import app, db; app.app_context().push(); db.create_all()'"

# Enable and start services
sudo systemctl enable nginx
sudo systemctl enable postgresql
sudo systemctl enable race-console

sudo systemctl start postgresql
sudo systemctl start race-console
sudo systemctl start nginx

# Enable Nginx site
sudo ln -s /etc/nginx/sites-available/race-console /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Docker Installation

1. Dockerfile

FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV FLASK_APP=main.py

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

# Create app directory
WORKDIR /app

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install --no-cache-dir gunicorn

# Copy application code
COPY . .

# Create non-root user
RUN useradd --create-home --shell /bin/bash race && \
    chown -R race:race /app
USER race

# Expose port
EXPOSE 8000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# Start application
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "main:app"]

2. Docker Compose

version: '3.8'

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://race_user:race_password@db:5432/race_console
      - FLASK_SECRET_KEY=your-secret-key
      - FLASK_ENV=production
    depends_on:
      - db
      - redis
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=race_console
      - POSTGRES_USER=race_user
      - POSTGRES_PASSWORD=race_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - web
    restart: unless-stopped

volumes:
  postgres_data:

3. Run with Docker Compose

# Build and start services
docker-compose up -d

# View logs
docker-compose logs -f web

# Run database migrations
docker-compose exec web python -c "from app import app, db; app.app_context().push(); db.create_all()"

# Stop services
docker-compose down

Post-Installation Configuration

1. Initial Setup

  1. Access the application at your configured URL
  2. Navigate to Configuration → API Configuration
  3. Enter your AVEVA CONNECT credentials
  4. Test the connection
  5. Run asset discovery

2. Security Configuration

# Generate secure secret key
python -c "import secrets; print(secrets.token_hex(32))"

# Set up firewall (UFW on Ubuntu)
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

3. SSL Certificate Setup

Using Let's Encrypt (Certbot)

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d your-domain.com -d www.your-domain.com

# Test automatic renewal
sudo certbot renew --dry-run

Using Custom Certificate

# Copy certificates to secure location
sudo mkdir -p /etc/ssl/race-console
sudo cp your-certificate.crt /etc/ssl/race-console/
sudo cp your-private-key.key /etc/ssl/race-console/
sudo chmod 600 /etc/ssl/race-console/*

4. Monitoring Setup

# Install monitoring tools
sudo apt install htop iotop netstat-nat

# Setup log rotation
sudo tee /etc/logrotate.d/race-console << EOF
/var/log/race-console/*.log {
    daily
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 644 race-console race-console
    postrotate
        systemctl reload race-console
    endscript
}
EOF

Backup and Recovery

1. Database Backup

# Daily backup script
#!/bin/bash
BACKUP_DIR="/backups/postgresql"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

pg_dump -h localhost -U race_user race_console | gzip > $BACKUP_DIR/race_console_$DATE.sql.gz

# Keep only last 30 days
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete

2. Application Backup

# Backup configuration and logs
tar -czf /backups/race_console_config_$(date +%Y%m%d).tar.gz \
    /opt/race-console/.env \
    /opt/race-console/config/ \
    /var/log/race-console/

3. Automated Backup (Cron)

# Add to crontab
sudo crontab -e

# Daily database backup at 2 AM
0 2 * * * /opt/race-console/scripts/backup.sh

# Weekly configuration backup at 3 AM on Sundays
0 3 * * 0 /opt/race-console/scripts/backup-config.sh

Troubleshooting Installation

Common Issues

Database Connection Issues

# Check PostgreSQL status
sudo systemctl status postgresql

# Test database connection
psql -h localhost -U race_user -d race_console

# Check database logs
sudo tail -f /var/log/postgresql/postgresql-*.log

Application Startup Issues

# Check application logs
sudo journalctl -u race-console -f

# Test application manually
cd /opt/race-console
source venv/bin/activate
python main.py

Nginx Configuration Issues

# Test Nginx configuration
sudo nginx -t

# Check Nginx logs
sudo tail -f /var/log/nginx/error.log

# Reload Nginx configuration
sudo systemctl reload nginx

Performance Tuning

Database Optimization

-- PostgreSQL configuration tuning
-- Add to postgresql.conf

shared_buffers = 256MB
effective_cache_size = 1GB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200

Application Optimization

# gunicorn.conf.py tuning
workers = multiprocessing.cpu_count() * 2 + 1
worker_connections = 1000
max_requests = 1000
max_requests_jitter = 100
timeout = 120

Maintenance

Regular Maintenance Tasks

# Weekly maintenance script
#!/bin/bash

# Update system packages
sudo apt update && sudo apt upgrade -y

# Clean up old logs
find /var/log/race-console -name "*.log.*" -mtime +7 -delete

# Vacuum database
sudo -u postgres psql -d race_console -c "VACUUM ANALYZE;"

# Restart application if needed
sudo systemctl restart race-console

Health Monitoring

# Check application health
curl -f http://localhost:8000/health

# Monitor system resources
htop
iotop
df -h

Version: beta

On this page