Skip to main content

Installation

System Requirements:

Automatic Installation​

To get started, scaffold the project with the mbc-cqrs-serverless CLI. Run the following commands. This will create a new project directory, and populate the directory with the initial core mbc-cqrs-serverless files and supporting modules, creating a conventional base structure for your project.

npm i -g @mbc-cqrs-serverless/cli
mbc new project-name

If you're new to mbc-cqrs-serverless, see the project structure docs for an overview of all the possible files and folders in your application.

Run the Development Server​

  1. Run npm run build to build the project in watch mode.
  2. Open another terminal session and run npm run offline:docker to start Docker services (DynamoDB Local, MySQL, LocalStack).
  3. Wait ~30 seconds for MySQL to fully start, then open another terminal and run npm run migrate to migrate RDS and DynamoDB tables.
  4. Finally, run npm run offline:sls to start serverless offline mode.
AWS Credentials for Local Development

Local development uses LocalStack to emulate AWS services. You do not need real AWS credentials — set dummy values in your .env file:

AWS_ACCESS_KEY_ID=local
AWS_SECRET_ACCESS_KEY=local

After the server runs successfully, you can see:

DEBUG[serverless-offline-sns][adapter]: successfully subscribed queue "http://localhost:9324/101010101010/notification-queue" to topic: "arn:aws:sns:ap-northeast-1:101010101010:MySnsTopic"
Offline Lambda Server listening on http://localhost:4000
serverless-offline-aws-eventbridge :: Plugin ready
serverless-offline-aws-eventbridge :: Mock server running at port: 4010
Starting Offline SQS at stage dev (ap-northeast-1)
Starting Offline Dynamodb Streams at stage dev (ap-northeast-1)

Starting Offline at stage dev (ap-northeast-1)

Offline [http for lambda] listening on http://localhost:3002
Function names exposed for local invocation by aws-sdk:
           * main: serverless-example-dev-main
Configuring JWT Authorization: ANY /{proxy+}

   ┌────────────────────────────────────────────────────────────────────────┐
   │                                                                        │
   │   ANY | http://localhost:3000/api/public                               │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │   ANY | http://localhost:3000/swagger-ui/{proxy*}                      │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │   ANY | http://localhost:3000/{proxy*}                                 │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │                                                                        │
   └────────────────────────────────────────────────────────────────────────┘

Server ready: http://localhost:3000 🚀

You can also use several endpoints:

Verify Your Setup

Open the Swagger UI in your browser to confirm the API server is running. You should see the interactive API documentation with all available endpoints.

Configuring Local Service Ports​

Version Note

Local port configuration feature was added in version 1.0.26.

If you have port conflicts with other services (e.g., another MySQL instance, another application using port 3000), you can configure the local service ports via environment variables in your .env file.

Available Port Variables​

VariableDefaultService
LOCAL_HTTP_PORT3000API Gateway (Serverless Offline)
LOCAL_LAMBDA_PORT3002Lambda HTTP endpoint
LOCAL_DYNAMODB_PORT8000DynamoDB Local
LOCAL_RDS_PORT3306MySQL (RDS)
LOCAL_S3_PORT4566LocalStack (S3)
LOCAL_SNS_PORT4002SNS
LOCAL_SQS_PORT9324SQS (ElasticMQ)
LOCAL_SQS_UI_PORT9325SQS Admin UI
LOCAL_SFN_PORT8083Step Functions Local
LOCAL_COGNITO_PORT9229Cognito Local
LOCAL_APPSYNC_PORT4001AppSync Simulator
LOCAL_EVENTBRIDGE_PORT4010EventBridge
LOCAL_SES_PORT8005Simple Email Service
LOCAL_DDB_ADMIN_PORT8001DynamoDB Admin UI

Example: Changing Ports​

To change the API Gateway port from 3000 to 3010 and MySQL port from 3306 to 3307, add the following to your .env file:

# Change API Gateway port to 3010
LOCAL_HTTP_PORT=3010

# Change MySQL port to 3307
LOCAL_RDS_PORT=3307

# Change DynamoDB port to 9000
LOCAL_DYNAMODB_PORT=9000

After changing the ports, restart all services:

  1. Stop all running services (Docker and Serverless Offline)
  2. Run npm run offline:docker to restart Docker services
  3. Run npm run offline:sls to restart Serverless Offline
tip

The port configuration is automatically applied to all related services including Docker Compose, Serverless Offline, and the DynamoDB stream trigger script. You only need to set the environment variables once in your .env file.

note

In the local environment, if you have trouble with the npm run migrate command or cannot log in with local Cognito, you will need to add more permissions to files and folders using the command below:

sudo chmod -R 777 ./infra-local/cognito-local
sudo chmod -R 777 ./infra-local/cognito-local/db/clients.json
sudo chmod -R 777 ./infra-local
sudo chmod -R 777 ./infra-local/docker-data/
sudo chmod -R 777 ./infra-local/docker-data/dynamodb-local

Next Steps​

Your local environment is ready. Here's the recommended path forward:

  1. Quickstart Tutorial — Build your first API endpoint in 15 minutes
  2. Project Structure — Understand what each generated file and folder does
  3. Architecture — Learn the CQRS and Event Sourcing concepts behind the framework
  4. Backend Development — Start implementing real features