Your First Project

Updated for nself v1.0.12 v1.0.12

Let's build your first ɳSelf project step by step. We'll create a complete backend for a todo application with user authentication, real-time data, and file storage.

What We'll Build

In this tutorial, we'll create a backend that includes:

• PostgreSQL database with todo items table
• GraphQL API with Hasura
• User authentication with JWT tokens
• File storage for attachments
• Real-time subscriptions for live updates

Step 1: Create Project Directory

First, create a new directory for your project and navigate to it:

mkdir todo-backend
cd todo-backend

Step 2: Initialize ɳSelf

Initialize a new ɳSelf project:

nself init

You'll be asked a few questions (or accept defaults):

• Project name
• Domain (default: local.nself.org)
• Which services to enable

What gets created:

todo-backend/
├── .env           # Your configuration
├── .env.secrets   # Sensitive credentials (auto-generated)
└── ɳSelf/         # Project directory

Step 3: Build and Start

Generate the Docker configuration and start services:

nself build    # Generate docker-compose.yml, nginx configs, etc.
nself start    # Launch all services

First start takes 2-5 minutes (downloading Docker images).

Check status:

nself status   # Service health
nself urls     # Access URLs

Step 4: Define Database Schema

ɳSelf uses a database-first approach. Create schema.dbml to define your todo application schema:

// Todo Application Schema

Table users {
  id uuid [pk, default: `gen_random_uuid()`]
  email varchar(255) [unique, not null]
  display_name varchar(255)
  created_at timestamp [default: `now()`]
  updated_at timestamp [default: `now()`]
}

Table todos {
  id uuid [pk, default: `gen_random_uuid()`]
  user_id uuid [not null, ref: > users.id]
  title varchar(255) [not null]
  description text
  completed boolean [default: false]
  due_date timestamp
  created_at timestamp [default: `now()`]
  updated_at timestamp [default: `now()`]
  
  indexes {
    user_id
    completed
    (user_id, completed) [name: "idx_user_completed"]
  }
}

Table todo_attachments {
  id uuid [pk, default: `gen_random_uuid()`]
  todo_id uuid [not null, ref: > todos.id]
  file_url varchar(500) [not null]
  file_name varchar(255) [not null]
  file_size integer
  mime_type varchar(100)
  uploaded_at timestamp [default: `now()`]
  
  indexes {
    todo_id
  }
}

Step 5: Create and Apply Migrations

Run the migration commands to apply your schema:

nself db migrate    # Generate migration from current schema state
nself db update     # Apply pending migrations
nself db seed       # Seed sample data

These commands:

1. Create versioned SQL migration files
2. Run the migrations against PostgreSQL
3. Optionally seed sample data for development

Sample users created (local/staging):

• admin@example.com (admin role)
• user@example.com (user role)
• demo@example.com (viewer role)

Step 6: Access Your Services

Trust SSL certificates for HTTPS access:

nself trust

Your backend is now running. Access the services:

Step 7: Test Your API

Open the Hasura Console at https://api.local.nself.org/console and try this GraphQL query:

mutation CreateTodo {
  insert_todos_one(object: {
    title: "Learn ɳSelf"
    description: "Complete the tutorial"
    user_id: "00000000-0000-0000-0000-000000000000"
  }) {
    id
    title
    created_at
  }
}

Next Steps

Add Authentication

Configure authentication rules in Hasura Console:

1. Go to Data -> todos -> Permissions
2. Add role "user"
3. Set row-level security: { "user_id": { "_eq": "X-Hasura-User-Id" } }

Install Plugins

Extend your backend with third-party integrations (112 available — 25 free, 87 paid):

# List available plugins
nself plugin list

# Install free plugins (no key needed)
nself plugin install analytics

# Install Pro plugins (requires active membership)
nself plugin install ai
nself plugin install notify

Deploy to Production

When ready for production:

# Create production environment
nself env create prod production

# Edit server configuration
# .environments/prod/server.json

# Deploy
nself deploy prod

Complete Project Files

Your project structure should now look like:

todo-backend/
├── .env                  # Main configuration
├── .env.secrets          # Sensitive credentials
├── schema.dbml           # Your database schema
├── docker-compose.yml    # Generated orchestration
├── nginx/                # Reverse proxy configs
├── postgres/             # Database initialization
│   └── migrations/       # SQL migrations
├── ssl/                  # SSL certificates
├── services/             # Custom services (if any)
└── ɳSelf/
    ├── migrations/       # Migration files
    ├── seeds/            # Seed data files
    ├── types/            # Generated types
    └── backups/          # Database backups

Summary

You've built a complete backend with:

• PostgreSQL database with custom schema
• GraphQL API with Hasura
• Authentication service ready
• File storage configured
• Local SSL domains working
• Development environment running

Next, explore:

• Database Workflow - DBML, migrations, seeding
• Services Overview - All available services
• Plugin System - Third-party integrations
• Production Deployment - Go to production