Custom Images

Build and deploy custom Docker images for your self-hosted Stormkit instance with specific runtimes, dependencies, and configurations

Self-hosted Stormkit instances provide the flexibility to customize Docker images according to your specific deployment needs. You can build custom images that include additional runtimes, dependencies, tools, or configurations that your applications require.

Understanding Stormkit’s Runtime Management

Stormkit uses mise (formerly rtx) to dynamically install and manage runtimes during application deployment. This approach provides several benefits:

• Flexible runtime versions - Each project can specify its own runtime version
• Automatic dependency management - Runtimes are installed on-demand
• Persistent storage - Dependencies are cached in the home folder for reuse

For most use cases, Stormkit’s dynamic runtime installation via mise is sufficient. Custom images are primarily needed for system-level dependencies that require root access.

Runtime vs Build-time Dependencies

Understanding the distinction between different types of dependencies is crucial:

Runtime Dependencies (Managed by mise):

• Programming language runtimes (Node.js, Python, Go, Rust, etc.)
• Language-specific package managers (npm, pip, cargo, etc.)
• Dependencies installed via mise configuration files
• Tools available through mise plugins

Build-time Dependencies (Require Custom Images):

• System packages requiring root access
• Custom build tools and utilities
• Base system configurations
• Native libraries and binaries

Official Stormkit Images

Before creating custom images, understand the official Stormkit images available:

ghcr.io/stormkit-io/hosting:latest

• Purpose: Serves the Stormkit API and deployed applications
• Responsibilities:
  • Web interface and API endpoints
  • Application hosting and serving
  • TLS certificate management
  • HTTP/HTTPS request handling
• Optimization: Optimized for production web serving

ghcr.io/stormkit-io/workerserver:latest

• Purpose: Runs background jobs and deployments
• Responsibilities:
  • Application builds and deployments
  • Build queue processing
  • Background job execution
  • Deployment pipeline management
• Optimization: Optimized for build and deployment tasks

Most custom dependencies should be added to the workerserver image, as this is where builds and deployments execute.

When to Customize Images

Custom images are primarily needed for:

System-Level Dependencies

Packages that require root access to install:

# Example: Image processing libraries
RUN apt-get update && apt-get install -y \
    imagemagick \
    graphicsmagick \
    libvips-dev

Custom Build Tools

Tools not available through standard package managers:

# Example: Custom deployment tool
RUN wget -O /usr/local/bin/custom-tool https://example.com/custom-tool \
    && chmod +x /usr/local/bin/custom-tool

Security Configurations

System-level security hardening and configurations:

# Example: Security configurations
RUN echo 'security.setting=value' >> /etc/app.conf

Pre-installed System Utilities

Libraries that multiple projects need:

# Example: Media processing tools
RUN apt-get update && apt-get install -y \
    ffmpeg \
    ghostscript

For runtime dependencies like Node.js versions or npm packages, use mise configuration instead of custom images. This provides more flexibility and easier updates.

Persisting Dependencies

Stormkit stores all runtime dependencies in the home folder. To persist these dependencies across upgrades and restarts, mount the home directory:

docker-compose.yaml

services:
  hosting:
    image: ghcr.io/stormkit-io/hosting:latest
    volumes:
      - hosting_home:/home/stormkit
    # Additional configuration...

  workerserver:
    image: ghcr.io/stormkit-io/workerserver:latest
    volumes:
      - workerserver_home:/home/stormkit
    # Additional configuration...

volumes:
  hosting_home:
  workerserver_home:

Persisting the home directory prevents re-downloading runtimes after container restarts and improves deployment performance.

Creating Custom Images

Basic Custom Image Example

Create a Dockerfile extending the official workerserver image:

Dockerfile

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

# Switch to root to install system packages
USER root

# Install system packages that require root access
RUN apt-get update && apt-get install -y \
    imagemagick \
    graphicsmagick \
    libvips-dev \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Install custom system tools
RUN wget -O /usr/local/bin/custom-tool https://example.com/custom-tool \
    && chmod +x /usr/local/bin/custom-tool

# Switch back to stormkit user (IMPORTANT!)
USER stormkit

# CMD is inherited from base image, no need to specify

Security Critical: Always switch back to the stormkit user after installing packages. Running as root in production is a security risk.

Advanced Example: Multiple Dependencies

Dockerfile.workerserver

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

USER root

# Install image processing libraries
RUN apt-get update && apt-get install -y \
    # Image processing
    imagemagick \
    graphicsmagick \
    libvips-dev \
    libvips-tools \
    # Video processing
    ffmpeg \
    # PDF processing
    ghostscript \
    poppler-utils \
    # Build tools
    build-essential \
    cmake \
    && rm -rf /var/lib/apt/lists/*

# Install additional Python packages system-wide (if needed)
RUN apt-get update && apt-get install -y \
    python3-dev \
    python3-pip \
    && rm -rf /var/lib/apt/lists/*

# Clean up
RUN apt-get clean && \
    rm -rf /var/cache/apt/* /tmp/* /var/tmp/*

USER stormkit

Custom Hosting Image Example

If you need to customize the hosting image:

Dockerfile.hosting

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

USER root

# Install SSL/TLS tools or monitoring agents
RUN apt-get update && apt-get install -y \
    certbot \
    monitoring-agent \
    && rm -rf /var/lib/apt/lists/*

USER stormkit

Building Custom Images

1. Create Dockerfile

   Create your Dockerfile in your project directory.

2. Build Image Locally

   docker build -t my-custom-stormkit-workerserver:latest -f Dockerfile .
   
3. Test Image (Optional)

   docker run --rm -it my-custom-stormkit-workerserver:latest /bin/bash
   
4. Tag for Registry (Optional)

   docker tag my-custom-stormkit-workerserver:latest \
     your-registry.com/stormkit-workerserver:latest
   
5. Push to Registry (Optional)

   docker push your-registry.com/stormkit-workerserver:latest
   

Pushing to a registry is optional if you’re building directly on your deployment server.

Configuring Docker Compose

Update your docker-compose.yaml to use custom images:

Option 1: Build from Local Dockerfile

docker-compose.yaml

services:
  workerserver:
    # Comment out the image line
    # image: ghcr.io/stormkit-io/workerserver:latest
    
    # Add build configuration
    build:
      context: .
      dockerfile: Dockerfile.workerserver
    
    container_name: workerserver
    restart: always
    env_file:
      - .env
    volumes:
      - workerserver_home:/home/stormkit
    depends_on:
      - db
      - redis

  hosting:
    # Keep using official image or customize
    image: ghcr.io/stormkit-io/hosting:latest
    # OR build custom hosting image:
    # build:
    #   context: .
    #   dockerfile: Dockerfile.hosting
    
    container_name: hosting
    restart: always
    ports:
      - "80:80"
      - "443:443"
    env_file:
      - .env
    volumes:
      - hosting_home:/home/stormkit
    depends_on:
      - db
      - redis
      - workerserver

volumes:
  hosting_home:
  workerserver_home:
  postgres_data:
  redis_data:

Option 2: Use Pre-built Image from Registry

docker-compose.yaml

services:
  workerserver:
    image: your-registry.com/stormkit-workerserver:latest
    container_name: workerserver
    # ... rest of configuration

Upgrading Custom Images

1. Pull Latest Base Image

   docker pull ghcr.io/stormkit-io/workerserver:latest
   
2. Rebuild Custom Image

   docker compose build --no-cache workerserver
   
3. Stop Services

   docker compose down workerserver hosting
   
4. Start with New Images

   docker compose up -d --build workerserver hosting
   
5. Verify Services

   docker compose ps
   docker compose logs -f workerserver hosting
   

The --build flag ensures Docker Compose rebuilds the image if there are changes.

Security Considerations

Follow these security best practices when creating custom images:

Use Official Base Images

# ✅ Good: Official Stormkit image
FROM ghcr.io/stormkit-io/workerserver:latest

# ❌ Bad: Unknown third-party image
FROM randomuser/stormkit:latest

Minimize Attack Surface

# ✅ Good: Install only what's needed
RUN apt-get update && apt-get install -y \
    imagemagick \
    && rm -rf /var/lib/apt/lists/*

# ❌ Bad: Installing unnecessary packages
RUN apt-get update && apt-get install -y \
    imagemagick \
    build-essential \
    git \
    curl \
    wget \
    vim \
    nano

Always Switch Back to Non-Root User

# ✅ Good: Switch back to stormkit user
USER root
RUN apt-get update && apt-get install -y imagemagick
USER stormkit

# ❌ Bad: Leaving as root user
USER root
RUN apt-get update && apt-get install -y imagemagick
# Missing: USER stormkit

Keep Images Updated

# Regularly update base images
docker pull ghcr.io/stormkit-io/workerserver:latest
docker compose build --no-cache

Scan for Vulnerabilities

# Scan images for security vulnerabilities
docker scan my-custom-stormkit-workerserver:latest

# Or use trivy
trivy image my-custom-stormkit-workerserver:latest

Best Practices

Layer Optimization

Combine RUN commands to reduce image layers:

# ✅ Good: Combined commands
RUN apt-get update && apt-get install -y \
    imagemagick \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# ❌ Bad: Separate commands create more layers
RUN apt-get update
RUN apt-get install -y imagemagick
RUN apt-get install -y ffmpeg
RUN rm -rf /var/lib/apt/lists/*

Clean Up Cache

Remove package manager cache to reduce image size:

RUN apt-get update && apt-get install -y \
    imagemagick \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

Use .dockerignore

Create a .dockerignore file to exclude unnecessary files:

.dockerignore

node_modules
.git
.env
*.log
.DS_Store

Document Customizations

Add comments explaining why packages are needed:

# Install image processing libraries for user avatar generation
RUN apt-get update && apt-get install -y \
    imagemagick \
    graphicsmagick \
    && rm -rf /var/lib/apt/lists/*

Troubleshooting

Build Fails: Permission Denied

Cause: Trying to install packages without switching to root.

Solution:

USER root
RUN apt-get update && apt-get install -y package-name
USER stormkit

Container Crashes After Custom Image

Cause: Not switching back to stormkit user.

Solution: Ensure USER stormkit is at the end of your Dockerfile.

Builds Are Slow

Cause: Not using Docker layer caching.

Solution:

• Order Dockerfile commands from least to most frequently changing
• Use BuildKit: DOCKER_BUILDKIT=1 docker build ...

Large Image Size

Cause: Not cleaning up package manager cache.

Solution:

RUN apt-get update && apt-get install -y package \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

Next Steps

Runtimes

Manage programming language runtimes with mise

Troubleshooting

Common issues and solutions