Getting Started

A practical path to build your first Nimbus app: install CLI, scaffold project, add one route, one model, and one background job.

Developer roadmap (30-45 min)

Install CLI and create a new app
Run server and verify first route
Add a Todo model and run migrations
Add create/list endpoints with validation
Dispatch a queue job and run worker
Enable Horizon and monitor queue metrics

1) Install the CLI

From the Nimbus repository directory:

cd /path/to/nimbus
go install ./cmd/nimbus

Ensure $HOME/go/bin is in your PATH. For zsh: export PATH="$HOME/go/bin:$PATH" (add to ~/.zshrc if needed).

2) Create a new app

nimbus new myapp
cd myapp
go mod tidy
nimbus serve

Server runs at http://localhost:3333 (or your PORT in .env).

3) Add your first route

In your app routes file:

app.Router.Get("/healthz", func(c *http.Context) error {
  return c.JSON(200, map[string]any{
    "status": "ok",
    "service": "myapp",
  })
})

4) Add model + migration

nimbus make:model Todo -m
nimbus migration:run

Then add fields like Title and Done in your model/migration.

5) Add queue-backed workflow

// Dispatch from a handler
queue.Dispatch(&jobs.SendWelcomeEmail{UserID: user.ID}).
  OnQueue("emails").
  Retries(5).
  Dispatch(c.Request.Context())

// Run worker in separate process
nimbus queue:work

6) Production defaults you should set early

Use QUEUE_DRIVER=redis (or database)
Set QUEUE_REDIS_VISIBILITY_TIMEOUT_SECONDS and QUEUE_DB_LEASE_SECONDS
Keep jobs idempotent and implement Failed()
Use WebSocket/Presence origin allowlists for realtime endpoints