انتقل إلى المحتوى الرئيسي

Installation

Detailed installation instructions for all platforms and configurations.

System Requirements​

Minimum Requirements​

ComponentRequirement
Node.jsLTS v22.x or v24.x
Yarnv1.22.x
RAM4 GB (8 GB recommended)
Disk Space2 GB for source + dependencies
OSWindows 10+, macOS 10.15+, Ubuntu 20.04+

Production Requirements​

ComponentRequirement
PostgreSQLv14+ (v16.x recommended)
Redisv6+
Node.jsLTS v22.x
Dockerv20+ with Compose v2.20+

Step-by-Step Installation​

1. Install Node.js​

Download and install the LTS version from nodejs.org.

Verify installation:

node --version   # Should output v22.x or later
npm --version    # Should output 10.x or later
تلميح

Use nvm (Linux/macOS) or nvm-windows to manage multiple Node.js versions. The repository includes an .nvmrc file.

2. Install Yarn​

npm install -g yarn
yarn --version   # Should output 1.22.x

3. Clone the Repository​

git clone https://github.com/ever-co/ever-gauzy.git
cd ever-gauzy

4. Bootstrap the Project​

yarn bootstrap

This command:

  • Installs all NPM dependencies across the monorepo
  • Links local packages via Lerna
  • Bootstraps the NX workspace
  • Runs any necessary postinstall scripts
ملاحظة

First-time bootstrap takes 5–15 minutes depending on your network speed and machine. Subsequent runs are faster due to caching.

5. Configure Environment​

Copy the sample environment file:

cp .env.sample .env

Key settings to review:

# ORM and Database
DB_ORM=typeorm                # Options: typeorm | mikro-orm
DB_TYPE=better-sqlite3        # Options: sqlite | better-sqlite3 | postgres | mysql

# API and UI URLs
API_BASE_URL=http://localhost:3000
CLIENT_BASE_URL=http://localhost:4200

# JWT (change in production!)
JWT_SECRET=secretKey
JWT_REFRESH_TOKEN_SECRET=refreshSecretKey

See the Configuration guide for all available options.

6. Set Up Git Hooks (Optional)​

If you plan to contribute:

yarn prepare:husky

This installs Husky pre-commit hooks for code formatting and lint checks.

7. Start the Platform​

yarn start

This concurrently starts:

8. Access the Platform​

Open http://localhost:4200 and log in:

  • Super Admin: admin@ever.co / admin
  • Employee: employee@ever.co / 123456

Database Setup​

SQLite (Default — Development/Demo)​

No additional setup required. SQLite is used by default with DB_TYPE=better-sqlite3.

The database file is created automatically at ./gauzy.sqlite3.

  1. Install PostgreSQL v14+ (v16.x recommended):

    • macOS: brew install postgresql@16
    • Ubuntu: sudo apt install postgresql-16
    • Windows: Download from postgresql.org

  2. Create database and user:

CREATE USER gauzy WITH PASSWORD 'gauzy_password';
CREATE DATABASE gauzy OWNER gauzy;
GRANT ALL PRIVILEGES ON DATABASE gauzy TO gauzy;
  1. Update .env:
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=gauzy
DB_USER=gauzy
DB_PASS=gauzy_password

MySQL (Alternative)​

  1. Install MySQL v8.0+

  2. Create database:

CREATE DATABASE gauzy CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'gauzy'@'localhost' IDENTIFIED BY 'gauzy_password';
GRANT ALL PRIVILEGES ON gauzy.* TO 'gauzy'@'localhost';
FLUSH PRIVILEGES;
  1. Update .env:
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=gauzy
DB_USER=gauzy
DB_PASS=gauzy_password

Optional Services​

Redis​

Redis is recommended for production caching. Without it, Gauzy uses in-memory caching.

# Install
# macOS: brew install redis
# Ubuntu: sudo apt install redis-server

# Update .env
REDIS_ENABLED=true
REDIS_URL=redis://localhost:6379

OpenSearch​

OpenSearch provides full-text search capabilities. Without it, Gauzy uses database-level search.

See the Docker Compose guide for the easiest OpenSearch setup.

MinIO (S3-Compatible Storage)​

For production file storage. Without it, files are stored on the local filesystem.

FILE_PROVIDER=S3
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1
AWS_S3_BUCKET=gauzy

Email (SMTP)​

Configure SMTP for email features (invitations, password reset, etc.):

MAIL_FROM_ADDRESS=gauzy@your-domain.com
MAIL_HOST=smtp.gmail.com
MAIL_PORT=465
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password

Platform-Specific Notes​

Windows​

  • Use PowerShell or Windows Terminal (not cmd.exe)
  • If you encounter EPERM or symlink errors, enable Developer Mode in Windows Settings
  • Some native modules may require Visual Studio Build Tools

macOS​

  • Xcode Command Line Tools are required: xcode-select --install
  • On Apple Silicon (M1/M2/M3), all dependencies should work natively

Linux​

  • Build essentials are required: sudo apt install build-essential
  • Python 3 may be needed for some native modules: sudo apt install python3

Useful Commands​

CommandDescription
yarn startStart API + UI
yarn start:apiStart API only
yarn start:uiStart UI only
yarn seedSeed database with initial data
yarn seed:allSeed with extensive demo data (~10 min)
yarn buildBuild all projects
yarn testRun tests
yarn lintRun linter
yarn bootstrapInstall deps & bootstrap workspace
yarn prepare:huskySet up Git hooks

Next Steps​