Skip to content

Installation Guide

This guide provides step-by-step instructions for installing faneX-ID in various environments.

Requirements

Hardware Requirements

Component Minimum Recommended Production
CPU 1 vCPU 2 vCPU 4+ vCPU
RAM 1 GB 4 GB 8+ GB
Storage 2 GB 10 GB 50+ GB
Network 10 Mbps 100 Mbps 1 Gbps

Software Requirements

  • Operating System:
  • Linux (Debian 12+, Ubuntu 22.04+, RHEL 9+)
  • Windows Server 2019+ (with WSL2 or Docker)

  • macOS (for development)

  • Container Runtime:

  • Docker 20.10+

  • Docker Compose 2.0+

  • Database (Production):

  • PostgreSQL 14+

  • SQLite (development only)

  • Network:

  • Port 8000 (Backend API)
  • Port 3000 (Frontend, production)
  • Port 5173 (Frontend, development)

Installation Methods

Step 1: Clone Repository

git clone https://github.com/faneX-ID/core.git
cd core

Step 2: Configure Environment

cp .env.example .env
nano .env

Required Environment Variables:

# Database Configuration
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_USER=fanexid
POSTGRES_DB=fanexiddb

# Application Settings
PROJECT_NAME=faneX-ID
DEBUG=false
SECRET_KEY=  # Auto-generated if empty

# Optional: GitHub Token (for private repo access)
GITHUB_TOKEN=your_github_token_here

Step 3: Start Services

docker-compose up -d --build

Step 4: Verify Installation

# Check container status
docker-compose ps

# View logs
docker-compose logs backend
docker-compose logs frontend

# Check backend health
curl http://localhost:8000/api/system/status

Step 5: Initial Login

  1. View backend logs to get admin password: 

    docker-compose logs backend | grep "INITIAL ADMIN"

  2. Access frontend:

  3. Development: http://localhost:5173

  4. Production: http://localhost:3000

  5. Login with:

  6. Username: admin
  7. Password: (from logs)

Method 2: Home Assistant Add-on

Prerequisites

  • Home Assistant installed
  • HACS installed (optional, for easier installation)

Installation Steps

  1. Add Repository:
  2. Go to Settings → Add-ons → Add-on Store
  3. Click three dots → Repositories

  4. Add: https://github.com/faneX-ID/homeassistant-addon

  5. Install Add-on:

  6. Find faneX-ID in add-on list
  7. Click Install

  8. Wait for installation to complete

  9. Configure:

  10. Click Configuration tab
  11. Enter GitHub token (required for private repo)
  12. Configure other settings as needed

  13. Click Save

  14. Start Add-on:

  15. Click Start
  16. Wait for startup
  17. Access via Home Assistant sidebar (Ingress)

Method 3: Manual Installation

Backend Installation

  1. Install Python 3.13+

  2. Install Dependencies: 

    cd backend
pip install -r requirements.txt

  3. Configure Environment: 

    export DATABASE_URL="postgresql://user:pass@localhost/fanexiddb"
export SECRET_KEY="your-secret-key"

  4. Run Migrations: 

    alembic upgrade head

  5. Start Backend: 

    uvicorn app.main:app --host 0.0.0.0 --port 8000

Frontend Installation

  1. Install Node.js 20+

  2. Install Dependencies: 

    cd frontend
npm install

  3. Build Frontend: 

    npm run build

  4. Serve Frontend: 

    # Development
npm run dev

# Production (using nginx or similar)
npm run build
# Serve dist/ directory

Post-Installation Configuration

1. Admin Panel Setup

  1. Access Admin Panel:
  2. Navigate to /admin in browser

  3. Login with admin credentials

  4. Configure Company:

  5. Set company name
  6. Add support contact information

  7. Configure base URL

  8. SSL Configuration:

  9. Generate self-signed certificate OR
  10. Upload custom SSL certificate
  11. Configure domain

2. Database Setup

PostgreSQL (Production)

  1. Create Database: 

    CREATE DATABASE fanexiddb;
CREATE USER fanexid WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE fanexiddb TO fanexid;

  2. Update Environment: 

    DATABASE_URL=postgresql://fanexid:secure_password@localhost:5432/fanexiddb

  3. Run Migrations: 

    docker-compose exec backend alembic upgrade head

3. Integration Configuration

  1. Access Integrations:
  2. Go to Integrations page

  3. Browse available integrations

  4. Install Integrations:

  5. Click Install on desired integration
  6. Configure credentials

  7. Test connection

  8. Configure System Integrations:

  9. Active Directory
  10. Microsoft Entra ID
  11. SMTP/Email
  12. GitHub (for updates)

Verification

Health Checks

  1. Backend Health: 

    curl http://localhost:8000/api/system/status

  2. Frontend Access:

  3. Open browser to frontend URL

  4. Verify login page loads

  5. Database Connection:

  6. Check backend logs for database errors
  7. Verify migrations completed

Functional Tests

  1. Login Test:
  2. Login with admin credentials

  3. Verify dashboard loads

  4. API Test:

  5. Access API documentation: http://localhost:8000/docs

  6. Test API endpoints

  7. Integration Test:

  8. Install test integration
  9. Verify integration works

Troubleshooting

Common Issues

  1. Port Already in Use:
  2. Check what's using the port: lsof -i :8000
  3. Change port in docker-compose.yml

  4. Stop conflicting service

  5. Database Connection Failed:

  6. Verify database is running
  7. Check connection string
  8. Verify credentials

  9. Check firewall rules

  10. Container Won't Start:

  11. Check logs: docker-compose logs
  12. Verify environment variables
  13. Check disk space

  14. Review resource limits

  15. Frontend Not Loading:

  16. Check backend is running
  17. Verify API URL in frontend config
  18. Check browser console for errors
  19. Verify CORS settings

Next Steps

After successful installation:

  1. Security Hardening: Security Guide
  2. Production Deployment: Deployment Guide
  3. Monitoring Setup: Maintenance Guide
  4. Backup Configuration: Maintenance Guide

Installation complete? Proceed to the Deployment Guide for production setup.