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

# Installation

> Install and deploy your self-hosted Stormkit instance using Docker containers, PostgreSQL, and Redis

Stormkit is a self-hostable alternative to Vercel and Netlify, giving you full control over your deployment infrastructure. This guide will walk you through installing Stormkit on your server.

## Prerequisites

Before installing Stormkit, ensure your system meets the following requirements:

* **Docker** and **Docker Compose** installed
* **Linux server** (Ubuntu 20+, Debian 11+, Fedora 39+, Rocky Linux 10) or **macOS** (Sonoma)
* **Minimum 2GB RAM** and **2 CPU cores** recommended
* **PostgreSQL 14+** (can be run via Docker)
* **Redis 7+** (can be run via Docker)

## Quick Installation

The fastest way to get started is using the official installation script:

```bash theme={null}
curl -sSL https://www.stormkit.io/install.sh | sh
```

This script will:

<Steps>
  <Step title="Install Docker">
    Automatically detect and install Docker if not already present on your system.
  </Step>

  <Step title="Configure Environment">
    Prompt you to configure necessary environment variables for your Stormkit instance.
  </Step>

  <Step title="Choose Deployment Method">
    Ask whether to use Docker Compose (single machine) or Docker Swarm (clustering).
  </Step>

  <Step title="Start Services">
    Pull the required Docker images and start all Stormkit services.
  </Step>
</Steps>

<Note>
  The installation script has been tested on Ubuntu (20, 22, 24), Darwin (Sonoma), Fedora (39, 40), Debian (11, 12), and Rocky Linux (10). If you encounter issues, please [submit them here](https://github.com/stormkit-io/www-stormkit-io/issues).
</Note>

## Manual Installation

For more control over the installation process, you can set up Stormkit manually using Docker Compose.

### Step 1: Create Project Directory

```bash theme={null}
mkdir stormkit-self-hosted
cd stormkit-self-hosted
```

### Step 2: Create Environment File

Create a `.env` file with the required configuration:

```bash .env theme={null}
# Redis Configuration
REDIS_ADDR=redis:6379

# PostgreSQL Configuration
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_DB=stormkit_db
POSTGRES_USER=stormkit_admin
POSTGRES_PASSWORD=your_secure_password_here
POSTGRES_SSL=disable

# Stormkit Configuration
STORMKIT_APP_SECRET=your_random_secret_key_here
STORMKIT_API_URL=http://api.yourdomain.com
STORMKIT_APP_URL=https://yourdomain.com
STORMKIT_HTTPS=on

# Runner Configuration
STORMKIT_RUNNER_CONCURRENCY=4
STORMKIT_DEPLOYER_SERVICE=local

# Optional: Monitoring
PROMETHEUS_METRICS=false
PROMETHEUS_PORT=2112
```

<Warning>
  Replace `your_secure_password_here` and `your_random_secret_key_here` with strong, randomly generated values. Never use default passwords in production.
</Warning>

### Step 3: Create Docker Compose File

Create a `docker-compose.yaml` file:

```yaml docker-compose.yaml theme={null}
volumes:
  stormkit:
  postgres_data:
  redis_data:

services:
  db:
    image: postgres:17
    container_name: database
    restart: always
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_DB=${POSTGRES_DB}
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    container_name: redis
    image: redis:7
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  workerserver:
    image: ghcr.io/stormkit-io/workerserver:latest
    container_name: workerserver
    restart: always
    env_file:
      - .env
    depends_on:
      - db
      - redis
    volumes:
      - stormkit:/home/stormkit

  hosting:
    image: ghcr.io/stormkit-io/hosting:latest
    container_name: hosting
    restart: always
    ports:
      - "80:80"
      - "443:443"
    env_file:
      - .env
    depends_on:
      - db
      - redis
      - workerserver
    volumes:
      - stormkit:/home/stormkit
```

### Step 4: Start Services

<Steps>
  <Step title="Pull Docker Images">
    ```bash theme={null}
    docker compose pull
    ```
  </Step>

  <Step title="Start All Services">
    ```bash theme={null}
    docker compose up -d
    ```
  </Step>

  <Step title="Verify Services are Running">
    ```bash theme={null}
    docker compose ps
    ```

    All services should show as "Up" or "running".
  </Step>

  <Step title="Check Logs">
    ```bash theme={null}
    docker compose logs -f
    ```

    Press `Ctrl+C` to stop following logs.
  </Step>
</Steps>

## Docker Images

Stormkit uses two main Docker images:

### ghcr.io/stormkit-io/hosting:latest

* Serves the Stormkit web interface and API
* Handles serving your deployed applications
* Manages TLS certificates and HTTPS connections
* Optimized for production web serving

### ghcr.io/stormkit-io/workerserver:latest

* Runs background jobs and deployment pipelines
* Handles application builds and deployments
* Processes build queues
* Manages deployment workers

## Required Services

### PostgreSQL 14+

Stormkit requires a PostgreSQL database to store:

* User accounts and authentication data
* Application and deployment configurations
* Build logs and deployment history
* System settings and preferences

The recommended image is `postgres:17` as shown in the docker-compose.yaml above.

### Redis 7+

Redis is used for:

* Job queue management
* Caching frequently accessed data
* Session storage
* Real-time deployment status updates

The recommended image is `redis:7`.

## Deployment Options

<CodeGroup>
  ```bash Docker Compose (Single Machine) theme={null}
  # Recommended for single-server deployments
  docker compose up -d
  ```

  ```bash Docker Swarm (Clustering) theme={null}
  # Initialize swarm (run once)
  docker swarm init

  # Deploy stack
  docker stack deploy -c docker-compose.yaml stormkit
  ```
</CodeGroup>

<Note>
  For single-machine deployments, **Docker Compose** is recommended for its simplicity. For scalability and clustering scenarios, consider **Docker Swarm** or other container orchestration tools.
</Note>

## Post-Installation Steps

<Steps>
  <Step title="Access Stormkit">
    Open your browser and navigate to your configured `STORMKIT_APP_URL`.
  </Step>

  <Step title="Create Admin Account">
    On first launch, you'll be prompted to create an admin account with full access to the admin interface.
  </Step>

  <Step title="Configure Authentication">
    Set up GitHub, GitLab, or Bitbucket authentication to import private repositories. See the [Authentication](/self-hosting/authentication) guide.
  </Step>

  <Step title="Deploy Your First App">
    Import a repository and trigger your first deployment!
  </Step>
</Steps>

## Upgrading Stormkit

To upgrade your Stormkit instance to the latest version:

```bash theme={null}
# Pull latest images
docker compose pull

# Restart services
docker compose down
docker compose up -d
```

<Warning>
  Always backup your PostgreSQL database before upgrading. Run `docker compose exec db pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} > backup.sql` to create a backup.
</Warning>

## Environment Variables Reference

For a complete list of available environment variables and their descriptions, refer to the [official docker-compose.yaml](https://github.com/stormkit-io/bin/blob/main/docker-compose.yaml) file.

Key environment variables include:

* `STORMKIT_APP_SECRET` - Secret key for encrypting sensitive data
* `STORMKIT_API_URL` - URL where the API is accessible
* `STORMKIT_APP_URL` - URL where the web interface is accessible
* `STORMKIT_RUNNER_CONCURRENCY` - Number of concurrent deployments (default: 4)
* `POSTGRES_*` - Database connection settings
* `REDIS_ADDR` - Redis server address

## Advanced Configuration

### GitHub Actions Integration

By default, Stormkit runs deployments on the same machine as the workerserver. For better performance and CI control, you can configure GitHub Actions. See the [stormkit-io/runner](https://github.com/stormkit-io/runner) repository for instructions.

### Custom Domain Setup

Configure your DNS to point to your Stormkit server's IP address:

```
A     @              your.server.ip.address
A     api            your.server.ip.address
A     *              your.server.ip.address
```

Ensure `STORMKIT_APP_URL` and `STORMKIT_API_URL` in your `.env` file match your domain.

## Tutorials

* [Install Stormkit on Ubuntu Server and deploy a Next.js app](https://youtu.be/bLw0r3VKLrg)
* [How to Self-Host Stormkit on Hetzner Cloud](https://www.stormkit.io/tutorials/how-to-self-host-stormkit-on-hetzner-cloud)

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/self-hosting/authentication">
    Configure GitHub, GitLab, or Bitbucket authentication
  </Card>

  <Card title="Managing Users" icon="users" href="/self-hosting/managing-users">
    Control user access and sign-up modes
  </Card>

  <Card title="Custom Images" icon="docker" href="/self-hosting/custom-images">
    Build custom Docker images with specific dependencies
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/self-hosting/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>