> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://mise.jdx.dev/)** (polyglot tool version manager)

You can install Go and Node.js using Mise:

```bash theme={null}
# 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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/stormkit-io/stormkit-io.git
    cd stormkit-io
    ```
  </Step>

  <Step title="Start all services">
    This command starts the database, Redis, and all Stormkit services:

    ```bash theme={null}
    make dev
    ```

    This will:

    * Check all dependencies
    * Start Docker services (PostgreSQL and Redis)
    * Run database migrations
    * Build the runner binary
    * Start all Stormkit services
  </Step>

  <Step title="Access the application">
    After the services start, you can access:

    * **Landing page**: [https://localhost:5500](https://localhost:5500)
    * **Application**: [https://localhost:5400](https://localhost:5400)
    * **API**: [http://api.localhost:8888](http://api.localhost:8888)
  </Step>
</Steps>

## Available Make Commands

The Makefile provides several commands to help with development:

<CodeGroup>
  ```bash Development theme={null}
  # Start all services with dependency checks
  make dev

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

  # Restart hosting and workerserver services
  make restart
  ```

  ```bash Testing theme={null}
  # Run all tests (frontend and backend)
  make test

  # Run only backend tests
  make test-be

  # Run only frontend tests
  make test-fe

  # Run frontend tests in watch mode
  make test-fe-watch
  ```

  ```bash Database theme={null}
  # Create a new migration file
  make migration

  # Dump database schema to structure.sql
  make dump-schema

  # Reset database, redis, and build folder
  make reset-data
  ```

  ```bash Utilities theme={null}
  # Check all dependencies
  make check-deps

  # Display environment variables for debugging
  make print-env

  # Show available commands
  make help
  ```
</CodeGroup>

## Testing

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

### Setting Up Test Database

<Steps>
  <Step title="Start services">
    ```bash theme={null}
    docker compose up -d db redis
    ```
  </Step>

  <Step title="Create test database">
    ```bash theme={null}
    docker compose exec db createdb -U ${POSTGRES_USER} sktest
    ```
  </Step>
</Steps>

### Running Tests

<CodeGroup>
  ```bash All Tests theme={null}
  # Run both frontend and backend tests
  make test
  ```

  ```bash Backend Tests theme={null}
  # Run Go tests with coverage
  make test-be

  # This runs:
  # go test -tags=imageopt,alibaba -p 1 -v -failfast -coverprofile=coverage.out ./...
  # go test -p 1 -v -failfast ./src/lib/integrations/
  ```

  ```bash Frontend Tests theme={null}
  # Run frontend tests
  make test-fe

  # Run in watch mode for development
  make test-fe-watch
  ```
</CodeGroup>

## Generating Mocks

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

```bash theme={null}
# Generate mocks for all interfaces
mockery --case=underscore --dir ./ --tags=alibaba,imageopt --all --output=./src/mocks
```

Or using `go run` without installing mockery globally:

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

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

## 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:

```bash theme={null}
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:

```bash theme={null}
make dump-schema
```

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

## Resetting Development Data

If you need to start fresh:

```bash theme={null}
make reset-data
```

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

## Troubleshooting

### Services won't start

Run dependency checks:

```bash theme={null}
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:

```bash theme={null}
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](/contributing/overview).