Codakey
Play
← Back to nocobase

How to Deploy & Use nocobase

NocoBase Deployment and Usage Guide

1. Prerequisites

Before installing NocoBase, ensure you have the following:

Runtime & Tools:

  • Node.js 18.x or 20.x (TypeScript project requirement)
  • npm 9.x or higher, or yarn 1.x
  • Docker and Docker Compose (recommended for production deployment)
  • Git (for source installation)
  • Database: PostgreSQL 10+ or MySQL 5.7+ (SQLite for development only)

Accounts & API Keys (Optional for AI features):

  • OpenAI API key or compatible LLM provider credentials (for AI employee features)
  • SMTP credentials for email notifications
  • Cloud storage credentials (AWS S3, Aliyun OSS, etc.) for file management

2. Installation

NocoBase supports three installation methods:

Method 1: Docker (Recommended for Production)

# Create a directory for NocoBase
mkdir nocobase && cd nocobase

# Download the docker-compose.yml file
curl -L https://raw.githubusercontent.com/nocobase/nocobase/main/docker-compose.yml -O

# Start NocoBase with PostgreSQL
docker-compose up -d

# Access the application at http://localhost:13000

Method 2: Create NocoBase App (For Custom Development)

# Create a new NocoBase project
npx create-nocobase-app@latest my-nocobase-app

cd my-nocobase-app

# Install dependencies
npm install

# Configure your database in .env file
cp .env.example .env
# Edit .env with your database credentials

# Run database migrations
npm run nocobase db:sync

# Start the development server
npm run dev

Method 3: From Git Source (For Contributors)

# Clone the repository
git clone https://github.com/nocobase/nocobase.git
cd nocobase

# Install dependencies
yarn install

# Build packages
yarn build

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Setup database
yarn nocobase db:sync

# Start in development mode
yarn dev

# Or build for production
yarn build:packages

3. Configuration

Environment Variables (.env file)

Create a .env file in your project root with these key variables:

# Database Configuration (choose one)
DB_DIALECT=postgres
DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=nocobase
DB_USER=nocobase
DB_PASSWORD=your_password
DB_STORAGE=storage.db  # For SQLite

# OR for MySQL
DB_DIALECT=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=nocobase
DB_USER=nocobase
DB_PASSWORD=your_password

# Application Settings
APP_KEY=your_app_key_here  # Generate with: openssl rand -base64 32
API_BASE_PATH=/api/
API_BASE_URL=http://localhost:13000

# File Storage
STORAGE_TYPE=local
STORAGE_LOCAL_DEST=storage/uploads

# For cloud storage (AWS S3 example):
STORAGE_TYPE=s3
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=your-bucket
STORAGE_S3_ACCESS_KEY_ID=your-access-key
STORAGE_S3_SECRET_ACCESS_KEY=your-secret-key

# Email Configuration
MAIL_FROM=nocobase@example.com
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USER=your-email@example.com
MAIL_PASSWORD=your-password

# AI Features (Optional)
AI_OPENAI_API_KEY=sk-...
AI_OPENAI_BASE_URL=https://api.openai.com/v1

Plugin Configuration

NocoBase uses a plugin-based architecture. Enable/disable plugins in packages/app/client/src/plugins/ or via the admin UI after installation.

Key plugins include:

  • @nocobase/plugin-ai - AI employee functionality
  • @nocobase/plugin-file-manager - File management
  • @nocobase/plugin-workflow - Workflow automation
  • @nocobase/plugin-api-keys - API key management

4. Build & Run

Development Mode

# From source installation
yarn dev

# From create-nocobase-app
npm run dev

# Access the application at http://localhost:13000
# Admin credentials: admin@nocobase.com / admin123

Production Build

# Build all packages
yarn build

# Or using the build script
yarn build:packages

# Start production server
yarn start

# With PM2 process manager
pm2 start "yarn start" --name nocobase

Database Operations

# Sync database schema
yarn nocobase db:sync

# Run migrations
yarn nocobase db:migrate

# Rollback migrations
yarn nocobase db:rollback

# Seed initial data
yarn nocobase db:seed

5. Deployment

Platform Recommendations

1. Docker-based Deployment (Simplest)

# docker-compose.prod.yml
version: '3'
services:
  app:
    image: nocobase/nocobase:latest
    ports:
      - "13000:80"
    environment:
      - DB_DIALECT=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_DATABASE=nocobase
      - DB_USER=nocobase
      - DB_PASSWORD=${DB_PASSWORD}
      - APP_KEY=${APP_KEY}
    depends_on:
      - postgres
    volumes:
      - ./storage:/app/nocobase/storage
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=nocobase
      - POSTGRES_USER=nocobase
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

2. Kubernetes Deployment

# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nocobase
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nocobase
  template:
    metadata:
      labels:
        app: nocobase
    spec:
      containers:
      - name: nocobase
        image: nocobase/nocobase:latest
        ports:
        - containerPort: 80
        envFrom:
        - secretRef:
            name: nocobase-secrets
        volumeMounts:
        - name: storage
          mountPath: /app/nocobase/storage
      volumes:
      - name: storage
        persistentVolumeClaim:
          claimName: nocobase-storage-pvc

3. Traditional VPS/Cloud Server

# Install Node.js and dependencies
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs postgresql

# Clone and setup
git clone https://github.com/nocobase/nocobase.git
cd nocobase
npm install

# Build for production
npm run build

# Setup as systemd service
sudo nano /etc/systemd/system/nocobase.service

Recommended Platforms:

  • AWS: ECS with Fargate, or EC2 with RDS
  • Google Cloud: GKE with Cloud SQL
  • Azure: AKS with Azure Database for PostgreSQL
  • DigitalOcean: App Platform or Droplets with Managed Databases
  • Railway/Render: Simplified deployment with PostgreSQL included

6. Troubleshooting

Common Issues and Solutions

1. Database Connection Errors

# Check if database is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U nocobase -d nocobase

# Ensure database exists
createdb -U postgres nocobase

2. Port Already in Use

# Find process using port 13000
lsof -i :13000

# Kill the process
kill -9 <PID>

# Or change port in .env
APP_PORT=13001

3. Build Failures

# Clear node_modules and reinstall
rm -rf node_modules
rm -rf packages/*/node_modules
yarn install

# Clear build cache
yarn clean
yarn build

# Ensure Node.js version is compatible
node --version  # Should be 18.x or 20.x

4. Plugin Loading Issues

# Rebuild specific plugin
cd packages/plugins/@nocobase/plugin-ai
yarn build

# Check plugin dependencies
yarn why <package-name>

5. File Upload Problems

# Check storage directory permissions
chmod -R 755 storage
chown -R www-data:www-data storage  # For Apache/Nginx

# Verify storage configuration in .env
STORAGE_TYPE=local
STORAGE_LOCAL_DEST=storage/uploads

6. AI Features Not Working

  • Verify API keys in .env are correct
  • Check if AI plugin is enabled in admin panel
  • Ensure network can access AI service endpoints
  • Check browser console for CORS errors

7. Performance Issues

# Enable caching
REDIS_URL=redis://localhost:6379

# Optimize database
yarn nocobase db:optimize

# Check logs for slow queries
tail -f logs/nocobase.log

Getting Help:

← Project overviewView alternatives to nocobase →