1. MooseStack
  3. 5-Minute Quickstart

On this page

PrerequisitesStep 1: Install Moose (30 seconds)Run the installation scriptReload your shell configurationVerify moose command worksStep 2: Create Your Project (1 minute)Initialize your projectNavigate to your project directoryInstall dependenciesStart your development environmentStep 3: Understand Your Project (1 minute)Step 4: Test Your Pipeline (2 minutes)Navigate to your project in the new terminalRun the data generator workflowWatch for data processing logsQuery your dataStep 5: Hot Reload Schema Changes (1 minute)RecapNeed Help?

5-Minute Quickstart

5 minute setup
Zero config
Local ClickHouse, Redpanda, and APIs

Loading video player...

Prerequisites

Check that your pre-requisites are installed by running the following commands:

Before you start

Node.js 20+

Before you start

Node.js 20+

Required for TypeScript development

Download →

Required for TypeScript development

Download →

Docker Desktop

For local development environment (requires at least 2.5GB memory)

Download →

Docker Desktop

For local development environment (requires at least 2.5GB memory)

Download →

macOS/Linux

Windows works via WSL2

node --version
docker ps

macOS/Linux

Windows works via WSL2

node --version
docker ps
Docker Desktop Memory Requirements

Make sure Docker Desktop has at least 2.5GB of memory allocated. To check or change this setting, open Docker Desktop, go to Settings → Resources → Memory, and adjust the slider if needed. Learn more about Docker Desktop settings →

Already have ClickHouse running?

Skip the tutorial and add Moose as a layer on top of your existing database


Step 1: Install Moose (30 seconds)

Run the installation script

bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose

You should see this message: Moose vX.X.X installed successfully! (note that X.X.X is the actual version number)

If you see an error instead, check Troubleshooting below.

Reload your shell configuration

This step is required. Your current terminal doesn't know about the moose command yet.

source ~/.zshrc

Verify moose command works

moose --version

You should see:

moose X.X.X
If you see 'command not found'

Try these steps in order:

  1. Re-run the correct source command for your shell
  2. Close this terminal completely and open a new terminal window
  3. Run moose --version again
  4. If still failing, see Troubleshooting
Checkpoint

You should see the moose version number. Do not proceed to Step 2 until moose --version works.


Step 2: Create Your Project (1 minute)

Initialize your project

moose init my-analytics-app typescript

You should see output like:

✓ Created my-analytics-app✓ Initialized TypeScript project

Navigate to your project directory

cd my-analytics-app

Install dependencies

npm install

Wait for installation to complete.

Checkpoint

Dependencies installed successfully with no errors.

Start your development environment

moose dev
This may take a minute the first time.

Moose is:

  • Downloading Docker images for ClickHouse, Redpanda, and Temporal
  • Starting containers
  • Initializing databases
  • Starting the development server

Do not proceed until you see the "Started Webserver" message.

Created docker compose file⡗ Starting local infrastructure  Successfully started containers     Validated clickhousedb-1 docker container     Validated redpanda-1 docker container  Successfully validated red panda cluster     Validated temporal docker container  Successfully ran local infrastructure      Node Id: my-analytics-app::b15efaca-0c23-42b2-9b0c-642105f9c437      Starting development mode      Watching "/path/to/my-analytics-app/app"       Started Webserver.  👈 WAIT FOR THIS    Next Steps 💻 Run the moose 👉 `ls` 👈 command for a bird's eye view of your application and infrastructure 📥 Send Data to Moose	Your local development server is running at: http://localhost:4000/ingest
Checkpoint

Keep this terminal running. This is your Moose development server. You'll open a new terminal for the next step.

Step 3: Understand Your Project (1 minute)

Your project includes a complete example pipeline:

      • bar.ts
      • models.ts
      • transform.ts
      • barAggregated.ts
      • generator.ts
    • index.ts

Important: While your pipeline objects are defined in the child folders, they must be imported into the root index.ts (TypeScript) or main.py (Python) file for the Moose CLI to discover and use them.

export * from "./ingest/models";      // Data models & pipelinesexport * from "./ingest/transforms";  // Transformation logicexport * from "./apis/bar";           // API endpointsexport * from "./views/barAggregated"; // Materialized viewsexport * from "./workflows/generator"; // Background workflows

Step 4: Test Your Pipeline (2 minutes)

Important: Open a second terminal window

Keep your moose dev terminal running. You need a second terminal for the next commands.

Navigate to your project in the new terminal

In your new terminal window (not the one running moose dev):

cd my-analytics-app

Run the data generator workflow

Your project comes with a pre-built Workflow called generator that acts as a data simulator:

moose workflow run generator

You should see:

Workflow 'generator' triggered successfully

Watch for data processing logs

Switch to your first terminal (where moose dev is running). You should see new logs streaming:

POST ingest/Foo[POST] Data received at ingest API sink for FooReceived Foo_0_0 -> Bar_0_0 1 message(s)[DB] 17 row(s) successfully written to DB table (Bar)
Data is flowing!

These logs show your pipeline working: Workflow generates data → Ingestion API receives it → Data transforms → Writes to ClickHouse

If you don't see logs after 30 seconds:

  • Verify moose dev is still running in Terminal 1
  • Check Terminal 2 for error messages from the workflow command
  • Run docker ps to verify containers are running
View Temporal Dashboard

The workflow runs in the background, powered by Temporal. You can see workflow status at http://localhost:8080.

Query your data

Your application has a pre-built API that reads from your database. The API runs on localhost:4000.

In Terminal 2, call the API with curl:

curl "http://localhost:4000/api/bar"

You should see JSON data like:

[  {    "dayOfMonth": 15,    "totalRows": 67,    "rowsWithText": 34,    "maxTextLength": 142,    "totalTextLength": 2847  },  {    "dayOfMonth": 14,    "totalRows": 43,    "rowsWithText": 21,    "maxTextLength": 98,    "totalTextLength": 1923  }]
Checkpoint

You should see JSON data with analytics results. Your complete data pipeline is working!

Try query parameters:

curl "http://localhost:4000/api/bar?limit=5&orderBy=totalRows"
Port Reference
  • Port 4000: Your Moose application webserver (all APIs are running on this port)
  • Port 8080: Temporal UI dashboard (workflow management)
  • Port 18123: ClickHouse HTTP interface (direct database access)

Step 5: Hot Reload Schema Changes (1 minute)

  1. Open app/ingest/models.ts (TypeScript) or app/ingest/models.py (Python)
  2. Add a new field to your data model:
/** Analyzed text metrics derived from Foo */export interface Bar {  primaryKey: Key<string>; // From Foo.primaryKey  utcTimestamp: DateTime; // From Foo.timestamp  hasText: boolean; // From Foo.optionalText?  textLength: number; // From Foo.optionalText.length  newField?: string; // Add this new optional field}
  1. Save the file and watch your terminal

Switch to Terminal 1 (where moose dev is running). You should see Moose automatically update your infrastructure:

⠋ Processing Infrastructure changes from file watcher             ~  Table Bar:                  Column changes:                    + newField: String
Checkpoint

You should see the column change logged. Your API, database schema, and streaming topic all updated automatically!

Try it yourself: Add another field with a different data type and watch the infrastructure update in real-time.

Recap

You've built a complete analytical backend with:

What's Working

Type-safe ingestion pipeline with API and stream processing

ClickHouse database with dynamic schema management

Analytics API with filtering

Hot-reload development

Need Help?

FiveonefourFiveonefour
Fiveonefour Docs
MooseStackTemplates
Changelog
Source506
  • Overview
  • Quick Start
    • 5-Minute Quickstart
    • Use with Existing ClickHouse
  • Templates / Examples
Fundamentals
  • Moose Runtime
  • MooseDev MCP
  • Data Modeling
MooseStack in your App
  • App / API frameworks
Modules
  • Moose OLAP
  • Moose Streaming
  • Moose Workflows
  • Moose APIs
Deployment & Lifecycle
  • Moose Migrate
  • Moose Deploy
Reference
  • API Reference
  • Data Types
  • Table Engines
  • CLI
  • Configuration
  • Observability Metrics
  • Help
  • Changelog
Contribution
  • Documentation
  • Framework