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:

curl -sSL https://www.stormkit.io/install.sh | sh

This script will:

1. Install Docker

   Automatically detect and install Docker if not already present on your system.

2. Configure Environment

   Prompt you to configure necessary environment variables for your Stormkit instance.

3. Choose Deployment Method

   Ask whether to use Docker Compose (single machine) or Docker Swarm (clustering).

4. Start Services

   Pull the required Docker images and start all Stormkit services.

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.

Manual Installation

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

Step 1: Create Project Directory

mkdir stormkit-self-hosted
cd stormkit-self-hosted

Step 2: Create Environment File

Create a .env file with the required configuration:

.env

# 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

Replace your_secure_password_here and your_random_secret_key_here with strong, randomly generated values. Never use default passwords in production.

Step 3: Create Docker Compose File

Create a docker-compose.yaml file:

docker-compose.yaml

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

1. Pull Docker Images

   docker compose pull
   
2. Start All Services

   docker compose up -d
   
3. Verify Services are Running

   docker compose ps
   

   All services should show as “Up” or “running”.

4. Check Logs

   docker compose logs -f
   

   Press Ctrl+C to stop following logs.

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

Docker Compose (Single Machine)

# Recommended for single-server deployments
docker compose up -d

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

Post-Installation Steps

1. Access Stormkit

   Open your browser and navigate to your configured STORMKIT_APP_URL.

2. Create Admin Account

   On first launch, you’ll be prompted to create an admin account with full access to the admin interface.

3. Configure Authentication

   Set up GitHub, GitLab, or Bitbucket authentication to import private repositories. See the Authentication guide.

4. Deploy Your First App

   Import a repository and trigger your first deployment!

Upgrading Stormkit

To upgrade your Stormkit instance to the latest version:

# Pull latest images
docker compose pull

# Restart services
docker compose down
docker compose up -d

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.

Environment Variables Reference

For a complete list of available environment variables and their descriptions, refer to the official 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 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
• How to Self-Host Stormkit on Hetzner Cloud

Next Steps

Authentication

Configure GitHub, GitLab, or Bitbucket authentication

Managing Users

Control user access and sign-up modes

Custom Images

Build custom Docker images with specific dependencies

Troubleshooting

Common issues and solutions