Installation

Complete guide to installing and deploying the MarsAI film festival platform

Prerequisites

Before you begin, ensure you have the following installed on your system:

• Node.js 24+ (LTS version recommended)
• MySQL 8+
• npm (comes with Node.js)
• Git (for cloning the repository)

We recommend using nvm (Node Version Manager) to manage Node.js versions. This ensures compatibility across different projects.

Installing Node.js with nvm

# Install the LTS version of Node.js 24
nvm install 24.13.0

# Use this version
nvm use 24.13.0

# Verify installation
node --version

Project Structure

The MarsAI platform consists of two main components:

• Backend (back/) - Express.js REST API with MySQL database
• Frontend (front/) - React application built with Vite

marsai/
├── back/           # Backend API
│   ├── src/
│   ├── migrations/
│   ├── config/
│   └── index.js
└── front/          # Frontend application
    ├── src/
    └── vite.config.js

Backend Setup

1. Navigate to backend directory

   cd back
   
2. Install dependencies

   npm install
   

   This will install all required packages including:

   • express - Web framework
   • sequelize - ORM for MySQL
   • jsonwebtoken - Authentication
   • bcrypt - Password hashing
   • multer - File uploads
   • @aws-sdk/client-s3 - S3 storage integration
3. Configure environment variables

   Copy the example environment file:

   cp .env.example .env
   

   Edit .env with your configuration:

   .env

   PORT=3000
   
   # Database configuration
   DB_NAME=marsai_db
   DB_USER=marsai
   DB_PASSWORD=Mars2026!
   DB_HOST=127.0.0.1
   DB_PORT=3306
   
   # JWT configuration
   JWT_SECRET=3939a257017821afc405406c53cd22741720d24871e43ff24792a47045fdc083
   JWT_EXPIRES_IN=1h
   
   # Google OAuth (optional)
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   
   # Scaleway S3 Storage (optional)
   SCW_ACCESS_KEY=
   SCW_SECRET_KEY=
   SCW_BUCKET=
   
   # Email configuration (optional)
   SMTP_HOST=
   SMTP_PORT=587
   SMTP_SECURE=false
   SMTP_USER=
   SMTP_PASS=
   
   MAIL_FROM_EMAIL=
   MAIL_FROM_NAME=MarsAI Festival
   

   Generate a secure JWT secret using: openssl rand -hex 32

4. Create MySQL database

   Connect to your MySQL server and create the database:

   CREATE DATABASE marsai_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'marsai'@'localhost' IDENTIFIED BY 'Mars2026!';
   GRANT ALL PRIVILEGES ON marsai_db.* TO 'marsai'@'localhost';
   FLUSH PRIVILEGES;
   

   The database configuration is defined in back/config/config.json. Update this file if you use different credentials.

5. Run database migrations

   Sequelize CLI will create all necessary tables:

   npm run migrate
   

   This creates the following tables:

   • Users - User accounts (ADMIN, JURY, PRODUCER)
   • Categories - Film categories
   • Movies - Film submissions
   • Collaborators - Film crew members
   • Events - Festival events
   • Votes - Jury voting records
   • Awards - Award definitions
   • Sponsors - Festival sponsors
   • Reservations - Event reservations
   • NewsletterSubscribers - Newsletter subscriptions

   Migration troubleshooting

   If migrations fail:

   # Check database connection
   mysql -u marsai -p marsai_db
   
   # Undo last migration
   npx sequelize-cli db:migrate:undo
   
   # Undo all migrations
   npx sequelize-cli db:migrate:undo:all
   
   # Re-run migrations
   npm run migrate
   
6. Start the backend server

   npm start
   

   The API will be available at http://localhost:3000

   You should see:

   ✓ Connexion à la base de données MySQL établie avec succès
   ✓ API disponible sur http://localhost:3000
   

   The backend uses nodemon for auto-reloading during development. Any changes to .js files will automatically restart the server.

Frontend Setup

1. Navigate to frontend directory

   cd front
   
2. Install dependencies

   npm install
   

   This will install:

   • react & react-dom - React framework
   • vite - Build tool and dev server
   • react-router - Client-side routing
   • @tanstack/react-query - Data fetching and caching
   • axios - HTTP client
   • tailwindcss - CSS framework
   • @vidstack/react - Video player
   • react-i18next - Internationalization
   • zod & react-hook-form - Form validation
3. Configure API endpoint

   The frontend connects to the backend via the Axios instance in src/api/config.js:

   src/api/config.js

   const instance = axios.create({
     baseURL: "http://127.0.0.1:3000/",
     timeout: 10000,
   });
   

   For production, update the baseURL to point to your deployed backend API endpoint.

4. Start the development server

   npm start
   # or
   npm run dev
   

   The application will be available at http://localhost:5173

   Vite provides:

   • ⚡️ Instant hot module replacement (HMR)
   • 🚀 Lightning-fast cold starts
   • 🔧 Rich features and optimized builds

Running Both Servers

For convenience, you can run both servers simultaneously from the root directory:

# From the project root
npm run back    # Starts backend on port 3000
npm run front   # Starts frontend on port 5173

Or run them in separate terminal windows:

Terminal 1 - Backend

cd back
npm start

Verifying Installation

1. Check backend health

   Visit http://localhost:3000/ in your browser or use curl:

   curl http://localhost:3000/
   

   Expected response:

   {
     "message": "MarsAI Backend API is running"
   }
   
2. Check frontend

   Open http://localhost:5173 in your browser. You should see the MarsAI Festival homepage.

3. Test database connection

   The backend logs will show:

   ✓ Connexion à la base de données MySQL établie avec succès
   

   If you see this message, your database is properly connected.

Production Deployment

Backend Deployment

1. Set production environment variables

   Update your .env file with production values:

   NODE_ENV=production
   PORT=3000
   DB_HOST=your-production-db-host
   JWT_SECRET=your-strong-production-secret
   
2. Run migrations on production database

   NODE_ENV=production npm run migrate
   
3. Start the server

   NODE_ENV=production node index.js
   

   For production, consider using a process manager like PM2:

   npm install -g pm2
   pm2 start index.js --name marsai-backend
   pm2 save
   pm2 startup
   

Frontend Deployment

1. Update API endpoint

   Edit src/api/config.js to point to your production backend:

   const instance = axios.create({
     baseURL: "https://api.yourfestival.com/",
     timeout: 10000,
   });
   
2. Build for production

   npm run build
   

   This creates an optimized production build in the dist/ directory.

3. Deploy static files

   Deploy the contents of dist/ to your hosting provider (Netlify, Vercel, AWS S3, etc.)

   For a simple static server:

   npm run preview  # Test production build locally
   

Optional Configuration

YouTube Integration

The platform includes YouTube integration for film trailer management. To enable:

1. Set up Google OAuth credentials

   1. Go to Google Cloud Console
   2. Create a new project or select existing
   3. Enable YouTube Data API v3
   4. Create OAuth 2.0 credentials
   5. Add credentials to .env:

   GOOGLE_CLIENT_ID=your-client-id
   GOOGLE_CLIENT_SECRET=your-client-secret
   
2. Authenticate YouTube access

   Visit http://localhost:3000/google/auth to generate the authentication token.

   This is only required if you want to automatically upload trailers to YouTube. The platform works without this integration.

Email Notifications

Configure SMTP settings in .env to enable email notifications:

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_USER=[e-mail]
SMTP_PASS=your-email-password
MAIL_FROM_EMAIL=[e-mail]

The platform sends emails for:

• Film submission confirmations
• Newsletter subscriptions
• Jury assignment notifications

Troubleshooting

Port already in use

Change the port in .env (backend) or vite.config.js (frontend):

vite.config.js

export default defineConfig({
  plugins: [react(), tailwindcss()],
  server: {
    port: 5174  // Change port here
  }
});

Database connection failed

Verify your MySQL service is running:

# Check MySQL status
sudo systemctl status mysql

# Start MySQL if stopped
sudo systemctl start mysql

# Test connection
mysql -u marsai -p marsai_db

CORS errors in frontend

The backend has CORS configured for http://localhost:5173. If you use a different port, update back/index.js:

back/index.js

app.use(cors({
  origin: process.env.FRONTEND_URL || "http://localhost:5173",
  credentials: true
}));

File upload errors

Ensure the uploads/ directory exists and has write permissions:

mkdir -p back/uploads
chmod 755 back/uploads

Next Steps

Now that your platform is installed, check out the Quickstart Guide to:

• Create your first admin account
• Submit a film as a producer
• Vote on films as a jury member
• Manage users and content as an administrator