Deploying Kottster

Introduction

Kottster is an open source internal tool builder designed to help developers create admin panels, dashboards, and internal applications quickly. Built with React on the frontend and Node.js on the backend, Kottster provides a low-code approach to building internal tools while still allowing full customization through code.

Instead of building admin interfaces from scratch, Kottster provides pre-built components and database integrations that can be customized to match your specific needs. It supports multiple database connections and provides a visual builder for creating CRUD interfaces, tables, forms, and charts.

Key features of Kottster:

• Visual Builder: Drag-and-drop interface for creating admin panels
• Database Connections: Connect to PostgreSQL, MySQL, MongoDB, and more
• Pre-built Components: Tables, forms, charts, and other UI components
• Custom Code: Extend with custom React components and Node.js logic
• Authentication: Built-in user management and role-based access control
• API Integration: Connect to REST and GraphQL APIs
• Real-time Updates: WebSocket support for live data
• Export Options: Export data to CSV, Excel, and PDF
• Version Control: Track changes to your internal tools
• Self-hosted: Full control over your data and infrastructure

This guide walks through deploying Kottster on Klutch.sh using Docker, configuring database connections, and building your first internal tool.

Why Deploy Kottster on Klutch.sh

Deploying Kottster on Klutch.sh provides several advantages for building internal tools:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kottster without complex orchestration.

Persistent Storage: Attach persistent volumes for application data and configurations. Your tools survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your internal tools.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your tool complexity and user count.

Environment Variable Management: Securely store database credentials and API keys.

Custom Domains: Assign a custom domain for your internal tool portal.

Always-On Availability: Your internal tools remain accessible 24/7.

Prerequisites

Before deploying Kottster on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and Node.js
• Database connection details for your data sources
• (Optional) A custom domain for your Kottster instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Kottster on Klutch.sh.

Repository Structure

kottster-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

WORKDIR /app

# Install Kottster CLI
RUN npm install -g @kottster/cli

# Create Kottster project
RUN kottster create my-app --skip-install

WORKDIR /app/my-app

# Install dependencies
RUN npm install

# Build for production
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Expose the web interface port
EXPOSE 3000

# Start the application
CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Default	Description
NODE_ENV	No	development	Node environment (production recommended)
PORT	No	3000	Port for the web interface
DATABASE_URL	Yes	-	Primary database connection string
SECRET_KEY	Yes	-	Secret key for session encryption
ADMIN_EMAIL	No	-	Default admin user email
ADMIN_PASSWORD	No	-	Default admin user password

Deploying Kottster on Klutch.sh

Generate a Secret Key

Generate a secure secret key for session management:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Kottster deployment configuration"
git remote add origin https://github.com/yourusername/kottster-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kottster” or “internal-tools”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kottster Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000 (Kottster’s default port)

Set Environment Variables

Add the following environment variables:

Variable	Value
NODE_ENV	production
SECRET_KEY	Your generated secret key
DATABASE_URL	Your database connection string
ADMIN_EMAIL	Your admin email
ADMIN_PASSWORD	Your admin password

Attach Persistent Volumes

Add volumes for data persistence:

Mount Path	Recommended Size	Purpose
/app/my-app/data	5 GB	Application data and uploads
/app/my-app/logs	2 GB	Application logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Kottster container
• Provision an HTTPS certificate

Access Kottster

Once deployment completes, access your Kottster instance at https://your-app-name.klutch.sh.

Building Internal Tools

Creating Your First App

After logging in:

1. Navigate to the Dashboard
2. Click Create New App
3. Choose a template or start from scratch
4. Configure your database connection
5. Design your interface using the visual builder

Adding Database Connections

Connect to your data sources:

1. Go to Settings > Data Sources
2. Click Add Connection
3. Select your database type
4. Enter connection credentials
5. Test the connection

Supported databases:

• PostgreSQL
• MySQL / MariaDB
• MongoDB
• SQLite
• Microsoft SQL Server

Building CRUD Interfaces

Create data management interfaces:

1. Select a table from your connected database
2. Drag table component to your page
3. Configure columns and filters
4. Add create, edit, and delete actions
5. Set up permissions

Troubleshooting Common Issues

Database Connection Errors

• Verify connection string format
• Check network accessibility from Klutch.sh
• Ensure database credentials are correct

Build Failures

• Check Node.js version compatibility
• Review npm dependency issues
• Verify all required environment variables are set

Performance Issues

• Optimize database queries
• Enable caching for frequently accessed data
• Increase resource allocation

Additional Resources

• Official Kottster Website
• Kottster Documentation
• Kottster GitHub Repository

Conclusion

Deploying Kottster on Klutch.sh gives you a powerful internal tool builder with automatic builds, persistent storage, and secure HTTPS access. Build admin panels, dashboards, and custom applications without starting from scratch.