Troubleshooting

Common issues and solutions for self-hosted Stormkit instances

This guide covers common issues you may encounter when running a self-hosted Stormkit instance and their solutions.

Installation Issues

Docker Not Found

Problem: Installation script fails with “docker: command not found”.

Solution:

1. Install Docker

   Follow the official Docker installation guide for your platform:

   • Ubuntu
   • Debian
   • Fedora
   • macOS
2. Verify Installation

   docker --version
   docker compose version
   
3. Retry Installation

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

Permission Denied Errors

Problem: Docker commands fail with “permission denied” errors.

Solution:

Linux

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and log back in, or run:
newgrp docker

# Verify docker works without sudo
docker ps

On Linux, you may need to log out and log back in for group membership changes to take effect.

Database Issues

Database Connection Failed

Problem: Services fail to start with “connection refused” or “database does not exist” errors.

Solution:

1. Check Database Service

   docker compose ps db
   

   Ensure the database container shows as “Up” or “running”.

2. Check Database Logs

   docker compose logs db
   

   Look for initialization errors or authentication failures.

3. Verify Environment Variables

   .env

   POSTGRES_HOST=db
   POSTGRES_PORT=5432
   POSTGRES_DB=stormkit_db
   POSTGRES_USER=stormkit_admin
   POSTGRES_PASSWORD=your_password
   POSTGRES_SSL=disable
   

   Ensure all PostgreSQL variables are set correctly.

4. Restart Services

   docker compose down
   docker compose up -d
   

Database Migration Errors

Problem: Services fail with “migration failed” or “table does not exist” errors.

Solution:

# Stop services
docker compose down

# Remove database volume (WARNING: This deletes all data)
docker volume rm stormkit_postgres_data

# Start services fresh
docker compose up -d

# Monitor logs for successful migration
docker compose logs -f workerserver hosting

Removing the database volume will delete all data. Only do this for fresh installations or if you have a backup.

Redis Issues

Redis Connection Failed

Problem: Services log “redis: connection refused” errors.

Solution:

1. Check Redis Service

   docker compose ps redis
   
2. Verify Redis Address

   .env

   REDIS_ADDR=redis:6379
   

   For Docker Compose, use the service name redis (not localhost).

3. Test Redis Connection

   docker compose exec redis redis-cli ping
   # Should return: PONG
   
4. Restart Redis

   docker compose restart redis
   

API and Web Interface Issues

API Endpoints Return 500 Errors

Problem: When accessing the application, API endpoints like /api/auth/providers and /api/instance return 500 Internal Server Error.

Solution:

This is typically caused by DNS resolution issues with api.localhost.

Linux/macOS

# Add api.localhost to your hosts file
echo "127.0.0.1       api.localhost" | sudo tee -a /etc/hosts

# Verify it resolves correctly
ping -c 1 api.localhost

# Restart services
docker compose restart hosting workerserver

On Windows, you need to open Notepad (or any text editor) with administrative privileges to edit the hosts file.

Cannot Access Web Interface

Problem: Browser shows “connection refused” when accessing Stormkit.

Solution:

1. Verify Services Running

   docker compose ps
   

   All services should show as “Up”.

2. Check Port Bindings

   docker compose ps hosting
   

   Verify ports 80 and 443 are mapped correctly.

3. Check Firewall

   Ensure your firewall allows incoming connections on ports 80 and 443.

   # Ubuntu/Debian with ufw
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   
   # Fedora/RHEL with firewalld
   sudo firewall-cmd --add-service=http --permanent
   sudo firewall-cmd --add-service=https --permanent
   sudo firewall-cmd --reload
   
4. Verify URL Configuration

   .env

   STORMKIT_APP_URL=https://yourdomain.com
   STORMKIT_API_URL=https://api.yourdomain.com
   

   Ensure these match your actual domain.

HTTPS/TLS Certificate Errors

Problem: Browser shows SSL/TLS certificate warnings.

Solution:

1. Configure ACME Email

   .env

   STORMKIT_HTTPS=on
   STORMKIT_ACME_EMAIL=[e-mail]
   

   This enables automatic Let’s Encrypt certificates.

2. Verify Domain DNS

   Ensure your domain points to your server’s IP:

   dig yourdomain.com +short
   dig api.yourdomain.com +short
   
3. Restart Hosting Service

   docker compose restart hosting
   
4. Check Certificate Logs

   docker compose logs -f hosting | grep -i "acme\|certificate"
   

Let’s Encrypt requires your domain to be publicly accessible on port 80 for the HTTP-01 challenge.

Authentication Issues

GitHub App Creation Failed

Problem: Creating a GitHub App from the admin interface fails.

Solution:

1. Verify Callback URL

   Ensure STORMKIT_APP_URL is set correctly and accessible from the internet.

2. Check GitHub API Access

   curl -I https://api.github.com
   

   Verify your server can reach GitHub’s API.

3. Review Error Logs

   docker compose logs -f hosting | grep -i "github"
   

OAuth Redirect Mismatch

Problem: Git provider authentication fails with “redirect_uri_mismatch” error.

Solution:

1. Verify redirect URI in your Git provider OAuth app settings matches exactly:

   • GitHub: https://yourdomain.com/auth/github/callback
   • GitLab: https://yourdomain.com/auth/gitlab/callback
   • Bitbucket: https://yourdomain.com/auth/bitbucket/callback

2. Check STORMKIT_APP_URL in .env file matches your domain

3. Ensure HTTPS is enabled if using a custom domain:

   .env

   STORMKIT_HTTPS=on
   

Deployment Issues

Deployments Fail or Hang

Problem: Deployments remain in “pending” state or fail immediately.

Solution:

1. Check Workerserver Service

   docker compose ps workerserver
   docker compose logs -f workerserver
   
2. Verify Runner Concurrency

   .env

   STORMKIT_RUNNER_CONCURRENCY=4
   

   Ensure this value is appropriate for your server’s resources.

3. Check Disk Space

   df -h
   docker system df
   

   Ensure sufficient disk space for builds.

4. Review Build Logs

   Check the deployment logs in the Stormkit UI for specific error messages.

Runtime Installation Fails

Problem: Deployments fail with “runtime not found” or “mise installation failed”.

Solution:

1. Check Internet Connectivity

   docker compose exec workerserver ping -c 3 github.com
   

   Workerserver needs internet access to download runtimes.

2. Verify Runtime Configuration

   Go to Admin > System > Installed runtimes and ensure required runtimes are listed.

3. Enable Auto Install

   In runtime settings, toggle Auto install on to automatically install runtimes from version files.

4. Check Mise Version

   Upgrade mise to the latest version from the admin interface.

Build Cache Issues

Problem: Builds are unusually slow or don’t use cached dependencies.

Solution:

docker-compose.yaml

# Ensure home directory is persisted
services:
  workerserver:
    volumes:
      - workerserver_home:/home/stormkit

volumes:
  workerserver_home:

Restart services after adding volume:

docker compose down
docker compose up -d

Performance Issues

High Memory Usage

Problem: Docker containers consume excessive memory.

Solution:

1. Check Container Stats

   docker stats
   
2. Reduce Runner Concurrency

   .env

   STORMKIT_RUNNER_CONCURRENCY=2
   

   Lower values reduce memory usage but slow down parallel builds.

3. Set Memory Limits

   docker-compose.yaml

   services:
     workerserver:
       deploy:
         resources:
           limits:
             memory: 2G
   

Slow Database Queries

Problem: Application feels sluggish, database queries are slow.

Solution:

docker-compose.yaml

services:
  db:
    environment:
      - POSTGRES_SHARED_BUFFERS=256MB
      - POSTGRES_EFFECTIVE_CACHE_SIZE=1GB
    deploy:
      resources:
        limits:
          memory: 1G

Development Environment Issues

go: command not found

Problem: After running mise install, which reports “all tools are installed”, running make dev fails with “go: command not found”.

Solution:

The mise tools aren’t activated in your shell. Add mise activation to your shell configuration:

zsh

# Add mise activation to zsh
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

# Reload configuration
source ~/.zshrc

# Verify go is available
which go

See mise activation docs for more shell options.

Image Optimization Not Working

Problem: Image optimization features don’t work in local environment.

Solution:

Image optimization is disabled by default on local environments to avoid requiring additional dependencies.

To enable it:

1. Install required system packages (ImageMagick, libvips, etc.)
2. Build a custom Docker image with image optimization libraries
3. See Custom Images for detailed instructions

For self-hosted production instances, include image processing libraries in your custom Docker image if needed.

Logging and Debugging

Enable Debug Logging

Increase log verbosity for troubleshooting:

.env

DEBUG=3

Higher values (1-5) provide more verbose output.

View Service Logs

All Services

# Follow logs from all services
docker compose logs -f

# View last 100 lines
docker compose logs --tail=100

Export Logs for Support

# Export all logs to file
docker compose logs > stormkit-logs.txt

# Export with timestamps
docker compose logs -t > stormkit-logs-$(date +%Y%m%d).txt

Backup and Recovery

Backup Database

1. Create Backup

   docker compose exec db pg_dump -U stormkit_admin stormkit_db > backup.sql
   
2. Verify Backup

   ls -lh backup.sql
   
3. Store Securely

   Copy the backup file to a secure location:

   cp backup.sql /path/to/secure/backups/stormkit-$(date +%Y%m%d).sql
   

Restore Database

Restoring a database will overwrite all current data. Ensure you have a recent backup before proceeding.

# Stop services
docker compose down

# Start only database
docker compose up -d db

# Wait for database to be ready
sleep 5

# Restore backup
docker compose exec -T db psql -U stormkit_admin -d stormkit_db < backup.sql

# Start all services
docker compose up -d

Backup Volumes

# Backup all Docker volumes
docker run --rm \
  -v stormkit_postgres_data:/source:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/postgres-data-backup.tar.gz -C /source .

Getting Help

Community Support

• GitHub Issues: stormkit-io/stormkit-io
• GitHub Discussions: Community Q&A

Reporting Issues

When reporting issues, include:

1. Stormkit version - Check the version in the admin interface
2. Operating system and version
3. Docker version - docker --version
4. Docker Compose version - docker compose version
5. Error messages - Complete error output from logs
6. Steps to reproduce - How to trigger the issue
7. Environment variables (sanitized) - Remove sensitive values

Diagnostic Information

# Collect diagnostic information
echo "=== System Info ==="
uname -a

echo "\n=== Docker Version ==="
docker --version
docker compose version

echo "\n=== Service Status ==="
docker compose ps

echo "\n=== Container Stats ==="
docker stats --no-stream

echo "\n=== Disk Usage ==="
df -h
docker system df

echo "\n=== Recent Logs ==="
docker compose logs --tail=50

Next Steps

Installation

Back to installation guide

Runtimes

Configure programming language runtimes

Custom Images

Build custom Docker images

GitHub Issues

Report bugs and issues