Skip to main content

Getting Started

This guide walks you through creating your first Radish application — from blueprint to running app.

Installation​

Install Radish CLI globally via npm:

npm install -g radish-cli

Or use it locally in your project:

npm install --save-dev radish-cli

Quick Start: Full App​

The fastest path to a running application:

1. Create a Blueprint​

Create a blueprint file that defines your entities:

blueprints/app.types.json

{
  "version": 1,
  "defaults": {
    "owned": true,
    "timestamps": true,
    "adminRole": "ADMIN"
  },
  "entities": {
    "Task": {
      "label": "Task",
      "description": "A todo task",
      "plural": "tasks",
      "fields": {
        "title": {
          "type": "string",
          "required": true,
          "label": "Title"
        },
        "description": {
          "type": "string",
          "optional": true,
          "label": "Description"
        },
        "status": {
          "type": "enum",
          "values": ["todo", "in_progress", "done"],
          "default": "todo",
          "label": "Status"
        },
        "dueDate": {
          "type": "isoDate",
          "optional": true,
          "label": "Due Date"
        }
      },
      "filters": ["status", "dueDate"]
    }
  }
}

2. Generate the App​

# Full app (skeleton + datalayer + admin panel)
radish-cli create app my-task-app --schema blueprints/app.types.json
cd my-task-app

Or generate into an existing directory:

radish-cli create app my-task-app --schema blueprints/app.types.json --in-place

3. Configure Environment​

Set a session secret in .env (required for signed session cookies):

# .env — a random secret was auto-generated during create app
# Verify SESSION_SECRET or RADISH_ENCRYPTION_KEY is set
cat .env | grep -E 'SESSION_SECRET|RADISH_ENCRYPTION_KEY'

Ensure MongoDB is running locally (default: mongodb://localhost:27017).

4. Run the App​

npm install
npm run dev

5. Complete Setup​

On first launch, the app redirects to /setup where you create your admin account. This replaces manual database seeding — no dev auth bypass, no raw database manipulation.

After setup, you can access:

  • /admin — Admin panel with entity CRUD, user management, roles
  • /api/v1/tasks — REST API for your entities
  • /api/health — Health and metrics endpoint

6. Seed Roles (Optional)​

If you have a roles blueprint, sync roles to the database:

radish-cli seed --sync-roles

Note: The seed command skips admin user creation when the /setup route exists.

Datalayer Only​

If you only need the generated data layer (for an existing project):

radish-cli create datalayer . --schema blueprints/app.types.json

This creates the .radish/ directory with contracts, models, repos, services, and routes — without the skeleton, admin panel, or deployment artifacts. See Generated Code Overview for details.

Use the Generated Code​

Import and use the generated services in your SvelteKit pages:

import { TaskService } from '@generated/datalayer/services';
import type { Task, CreateTask } from '@generated/datalayer/contracts';
import { createTaskSchema } from '@generated/datalayer/contracts';

// Create a task
const task = await TaskService.create(ctx, {
  title: 'Complete documentation',
  status: 'todo',
  dueDate: new Date().toISOString()
});

// Validate input
const input = createTaskSchema.parse(userInput);

// Query tasks with date filtering and sorting
const tasks = await TaskService.list(ctx, {
  status: 'in_progress',
  sort: '-dueDate',
  limit: 10
});

Deploy​

Once your app is ready for production:

# One-time: install and configure the Coolify CLI
npm install -g @abeedoo/cfy
cfy setup

# Provision the app on Coolify
radish deploy init

# Tag and deploy
git tag v0.1.0
git push origin main --tags   # GitLab CI builds the Docker image

See Deployment Model for the full deployment pipeline.

Next Steps​