Skip to main content
This guide walks you through the steps to run the development environment after installing a Sonamu project.

​
Prerequisites

You must have completed the Installation guide and have a project created.

​
Running the Development Environment

The Sonamu development environment consists of three servers:
  • PostgreSQL - Database
  • API Server - Backend REST API (includes Sonamu UI)
  • Web Server - Frontend application
1

Start Database

Navigate to your project’s api directory and start the PostgreSQL container:
cd myapp/packages/api
pnpm docker:up
This command uses Docker Compose to run the PostgreSQL database in the background.
To verify the database is running correctly, you can check the container status with the docker ps command.
docker ps result
2

Run API Server

In the same api directory, start the development server:
pnpm dev
When the server starts successfully, you’ll see the following message:
🌲 Server listening on http://localhost:1028
This single command runs everything:The API server supports Hot Module Replacement (HMR), so it automatically restarts when code changes.
In the local development environment, the API server integrates and serves the Web app. It connects the Web directory’s Vite Dev Server as middleware to the API server, allowing everything to run on a single port.
Keep this terminal window open. It maintains the running API server.
3

Run Web Server (Optional)

If you want to focus on Web development or utilize Vite’s full features, open a new terminal window and start the development server separately in the web directory:
cd myapp/packages/web
pnpm dev
When the Vite development server starts, you’ll see the following message:
  VITE v5.x.x  ready in xxx ms

  ➜  Local:   http://localhost:3028/
  ➜  Network: http://192.168.x.x:3028/
If you run the Web server separately, you can access the frontend at http://localhost:3028. The Web server automatically proxies /api/* path requests to the API server (localhost:1028).
Two Development Modes
  • Integrated mode (recommended): Run only API server → Access everything at localhost:1028
  • Separated mode: Run API + Web separately → API at localhost:1028, Web at localhost:3028
The integrated mode is sufficient for most cases. Use separated mode only when focusing on Web development.

​
Verify Access

​
Integrated Mode (API server only)

You can access the following URLs in your browser:
ServiceURLDescription
Web Apphttp://localhost:1028Frontend application
API Serverhttp://localhost:1028/apiREST API endpoints
Sonamu UIhttp://localhost:1028/sonamu-uiEntity management interface

​
Separated Mode (Both API + Web servers running)

ServiceURLDescription
Web Apphttp://localhost:3028Frontend application
API Serverhttp://localhost:1028/apiREST API endpoints
Sonamu UIhttp://localhost:1028/sonamu-uiEntity management interface
Access the Web app to verify the Sonamu application is running correctly.

​
Sonamu UI Features

When you access http://localhost:1028/sonamu-ui in your browser, you can perform the following tasks:
  • Create and edit entities
  • Manage database migrations
  • View API endpoints
  • Visualize database schema
Sonamu UI

​
Stopping Servers

To stop the servers when you’re done developing:
  1. API Server (and Web server if running): Press Ctrl + C in each terminal to stop.
  2. Database: Run the following command in the api directory: 
pnpm docker:down
The docker:down command only stops the container; data is preserved. To completely reset the database, refer to the Database Management documentation.

​
Next Steps

Your development environment is ready! Now learn Sonamu’s core features through the following guides:

Creating Your First Entity

Use Sonamu UI to create your first entity and define the database schema.

API Development

Create REST APIs based on entities and implement business logic.

Frontend Integration

Use the auto-generated service layer to call APIs from the frontend.

Project Structure

Understand the directory structure and key files of a Sonamu project.