Local Development

Set up your local development environment for Stormkit

This guide will help you set up a local development environment for Stormkit.

Prerequisites

Before you begin, ensure you have the following installed:

• Go 1.25+
• Node.js 24+
• PostgreSQL 14+
• Redis 6+
• Docker
• Mise (polyglot tool version manager)

You can install Go and Node.js using Mise:

# Trust the dependencies specified in mise.toml and install them
mise trust && mise install

Project Structure

Understanding the project structure will help you navigate the codebase:

stormkit-io/
├── src/
│   ├── ce/                   # Community Edition (AGPL-3.0)
│   │   ├── api/              # REST API server
│   │   ├── hosting/          # Hosting service
│   │   ├── runner/           # Build and deployment runner
│   │   └── workerserver/     # Background job processing
│   ├── ee/                   # Enterprise Edition (Commercial)
│   │   ├── api/              # Enterprise API features
│   │   ├── hosting/          # Enterprise hosting features
│   │   └── workerserver/     # Enterprise background services
│   ├── lib/                  # Shared libraries and utilities
│   ├── migrations/           # Database migrations
│   ├── mocks/                # Test mocks and fixtures
│   ├── ui/                   # Frontend React application
│   └── www/                  # Landing page React application
├── scripts/                  # Build and deployment scripts
└── bin/                      # Compiled binaries

Component Overview

• Community Edition (src/ce/): Open source components under AGPL-3.0
• Enterprise Edition (src/ee/): Commercial features requiring a license
• Shared Libraries (src/lib/): Common utilities used by both editions
• Frontend (src/ui/): React-based web interface
• Landing Page (src/www/): Marketing website

Setting Up Development Environment

1. Clone the repository

   git clone https://github.com/stormkit-io/stormkit-io.git
   cd stormkit-io
   
2. Start all services

   This command starts the database, Redis, and all Stormkit services:

   make dev
   

   This will:

   • Check all dependencies
   • Start Docker services (PostgreSQL and Redis)
   • Run database migrations
   • Build the runner binary
   • Start all Stormkit services
3. Access the application

   After the services start, you can access:

   • Landing page: https://localhost:5500
   • Application: https://localhost:5400
   • API: http://api.localhost:8888

Available Make Commands

The Makefile provides several commands to help with development:

Development

# Start all services with dependency checks
make dev

# Start Docker services only (db, redis)
make start

# Restart hosting and workerserver services
make restart

Testing

Tests require PostgreSQL with a test database named sktest and Redis to be running.

Setting Up Test Database

1. Start services

   docker compose up -d db redis
   
2. Create test database

   docker compose exec db createdb -U ${POSTGRES_USER} sktest
   

Running Tests

All Tests

# Run both frontend and backend tests
make test

Generating Mocks

When adding or changing interfaces under src/lib (or other packages), generate testify mocks using mockery:

# Generate mocks for all interfaces
mockery --case=underscore --dir ./ --tags=alibaba,imageopt --all --output=./src/mocks

Or using go run without installing mockery globally:

go run github.com/vektra/mockery/v2@latest --case=underscore --dir ./ --tags=alibaba,imageopt --all --output=./src/mocks

After regenerating mocks, run gofmt, go vet, and go test ./..., then commit the updated files under src/mocks.

Environment Configuration

The .env file is automatically created from .env.example when you run make dev. Key environment variables include:

• Redis: REDIS_ADDR=localhost:6379
• PostgreSQL: POSTGRES_HOST=localhost, POSTGRES_PORT=5432
• API URL: STORMKIT_API_URL=http://api.localhost:8888
• App URL: STORMKIT_APP_URL=https://localhost:5400
• Runner Concurrency: STORMKIT_RUNNER_CONCURRENCY=4

Database Migrations

Creating a New Migration

To create a new migration file:

make migration

This creates a new file in src/migrations/ with the next numeric prefix and today’s date, e.g., 0021_2026-03-02.up.sql.

Dumping Schema

To dump the current database schema:

make dump-schema

This saves the schema to src/migrations/structure.sql.

Resetting Development Data

If you need to start fresh:

make reset-data

This will delete all Docker volumes, remove the build directory, and reset your local database and Redis data.

Troubleshooting

Services won’t start

Run dependency checks:

make check-deps

This verifies that Docker, Mise, and other dependencies are installed and running.

Port conflicts

If you have services running on the default ports, you may need to modify the .env file to use different ports.

Docker not running

Ensure Docker Desktop is running before executing make dev or make start.

Tests failing

Make sure the test database sktest exists:

docker compose exec db createdb -U ${POSTGRES_USER} sktest

Next Steps

Now that you have your development environment set up:

1. Explore the codebase structure
2. Run the test suite to ensure everything works
3. Check out open issues on GitHub
4. Start contributing!

For contribution guidelines, see the Contributing Overview.