Installation & Configuration
Complete Optimus CMS installation and deployment guide to help you quickly set up development and production environments.
System Requirements
Required Environment
- ✓Node.js >= 20.0.0 (recommended 20.11.0)
- ✓pnpm >= 8.15.1
- ✓Docker >= 20.10.0 & Docker Compose >= 2.0.0
- ✓MySQL >= 8.0
- ✓Redis >= 6.0
💡 Recommended Configuration
- Memory: 8GB or more
- Storage: 20GB or more available space
- Operating System: macOS, Linux, or Windows 10/11 (WSL2)
Quick Installation
Step 1: Clone the Project
git clone https://github.com/paul-leo/optimus-cms.git cd optimus-cms
Step 2: Install pnpm (if not installed)
npm install -g pnpm@8.15.1
Step 3: Configure Environment Variables
# Configure environment variables for API project cd packages/optimus-api cp env.example .env.local # Configure environment variables for Admin UI cd ../optimus-ui cp env.example .env.local # Configure environment variables for Client cd ../optimus-next cp env.example .env.local
Important: Please modify the configuration items in the .env.local file according to your actual environment
Step 4: One-Click Environment Initialization
# Return to project root directory cd ../.. # Run environment check and initialization (auto install dependencies, start database, initialize data) npm run doctor
The doctor command will automatically complete the following operations:
- Check Node.js and pnpm versions
- Install project dependencies
- Start Docker containers (MySQL, Redis, MinIO)
- Create database and table structures
- Import initial data
Step 5: Start Development Server
# Start all services npm run dev # Or start separately npm run dev:api # Start API service (port 8084) npm run dev:ui # Start Admin UI (port 8082) npm run dev:next # Start Client (port 8086)
Environment Variables Details
1. API Service Configuration (packages/optimus-api/.env.local)
# Application Configuration APP_PORT=8084 APP_ENV=development # Database Configuration DB_HOST=localhost DB_PORT=3306 DB_USERNAME=root DB_PASSWORD=your_password DB_DATABASE=optimus_cms # Redis Configuration REDIS_HOST=localhost REDIS_PORT=6379 REDIS_PASSWORD= REDIS_DB=0 # JWT Configuration JWT_SECRET=your_jwt_secret_key_change_in_production JWT_EXPIRES_IN=7d # Client User Authentication Secret CLIENT_USER_SECRET=your_client_secret_key # File Storage Configuration (MinIO/Aliyun OSS) OSS_TYPE=minio # minio or aliyun MINIO_ENDPOINT=localhost MINIO_PORT=9000 MINIO_ACCESS_KEY=minioadmin MINIO_SECRET_KEY=minioadmin MINIO_BUCKET=optimus-cms # Aliyun OSS (if using) # ALIYUN_OSS_ACCESS_KEY_ID= # ALIYUN_OSS_ACCESS_KEY_SECRET= # ALIYUN_OSS_BUCKET= # ALIYUN_OSS_REGION= # Logging Configuration LOG_LEVEL=debug # Change to info in production # Sentry Monitoring (optional) # SENTRY_DSN=
2. Admin UI Configuration (packages/optimus-ui/.env.local)
# API Service URL REACT_APP_API_BASE_URL=http://localhost:8084 # Application Port PORT=8082 # Upload File Size Limit (MB) REACT_APP_MAX_FILE_SIZE=10
3. Client Configuration (packages/optimus-next/.env.local)
# API Service URL (for client) NEXT_PUBLIC_API_BASE_URL=http://localhost:8084 # Application Port PORT=8086 # Client User Authentication Secret (must match API service) NEXT_PUBLIC_CLIENT_USER_SECRET=your_client_secret_key # Site Information NEXT_PUBLIC_SITE_NAME=Optimus CMS NEXT_PUBLIC_SITE_URL=http://localhost:8086
Manual Database Initialization
If `npm run doctor` fails to initialize the database automatically, you can manually execute the following steps:
1. Start Database Service
docker-compose -f docker-compose.local.yml up -d
2. Import Database Structure
# Use provided SQL file mysql -h localhost -u root -p optimus_cms < packages/optimus-api/db/kapok-minimal.sql
3. (Optional) Import Test Data
mysql -h localhost -u root -p optimus_cms < packages/optimus-api/db/seeds/test-data.sql
Access Application
🔐 Admin Dashboard
Access URL: http://localhost:8082
Default admin account:
Username: admin
Password: admin
🌐 Client Frontend
Access URL: http://localhost:8086
📡 API Service
API URL: http://localhost:8084
Health Check: http://localhost:8084/health
API Docs: http://localhost:8084/api/docs (if enabled)
Docker Production Deployment
Build Docker Image
# Build API service image docker build -t optimus-api:latest -f Dockerfile . # Build frontend image (if needed) docker build -t optimus-next:latest -f packages/optimus-next/Dockerfile packages/optimus-next
Start with Docker Compose
docker-compose up -d
FAQ
Q: What if the port is already in use?
A: You can modify the port number in the .env.local file of each project, or close the process occupying the port.
Q: Database connection failed?
A: Ensure Docker containers are running normally (`docker ps`), check if the database configuration in .env.local is correct.
Q: pnpm dependency installation failed?
A: Try clearing the cache: `pnpm store prune`, then reinstall: `pnpm install`
Q: How to reset the database?
A: Delete the database and re-import the SQL file, or run `npm run db:reset` (if this command is available).
Next Steps
Congratulations! You have successfully installed Optimus CMS. Now you can: