Guide Getting Started - osama1998H/Moca GitHub Wiki

Quick Start Guide

Install Moca, create a project, define your first MetaType, and interact with the API.

Prerequisites

  • Go 1.26+
  • PostgreSQL 16+
  • Redis 7+
  • Node.js 22+ (for Desk frontend, optional)

1. Install Moca CLI

go install github.com/osama1998H/moca/cmd/moca@latest

Or use the install script:

curl -fsSL https://raw.githubusercontent.com/osama1998H/moca/main/install.sh | sh

2. Create a Project

moca init my-project
cd my-project

This creates the project structure with moca.yaml, apps/, desk/, and sites/. The builtin core package lives in the framework at pkg/builtin/core; it is not copied into the project tree.

3. Configure Database

Edit moca.yaml:

database:
  host: localhost
  port: 5432
  user: moca
  password: your_password
  name: moca_dev

redis:
  host: localhost
  port: 6379

4. Create a Site

moca site create mysite

This creates a PostgreSQL schema for the site and seeds core DocTypes (User, Role, DocType, etc.).

5. Start the Dev Server

moca serve

This starts the API server, worker, and scheduler in a single process. The API is available at http://localhost:8000.

6. Define a MetaType

Create a DocType JSON definition in your app:

{
  "name": "Task",
  "module": "Project",
  "naming": "autoincrement",
  "fields": [
    { "fieldname": "title", "fieldtype": "Data", "label": "Title", "reqd": 1 },
    { "fieldname": "status", "fieldtype": "Select", "label": "Status", "options": "Open\nIn Progress\nCompleted", "default": "Open" },
    { "fieldname": "description", "fieldtype": "Text Editor", "label": "Description" },
    { "fieldname": "assigned_to", "fieldtype": "Link", "label": "Assigned To", "options": "User" }
  ]
}

7. Migrate the Database

moca db migrate --site mysite

8. Interact with the API

# Create a document
curl -X POST http://localhost:8000/api/v1/document/Task \
  -H "Content-Type: application/json" \
  -H "X-Moca-Site: mysite" \
  -d '{"title": "My First Task", "status": "Open"}'

# List documents
curl http://localhost:8000/api/v1/document/Task \
  -H "X-Moca-Site: mysite"

# Get a single document
curl http://localhost:8000/api/v1/document/Task/1 \
  -H "X-Moca-Site: mysite"

Next Steps