Deploying Kaneo

Introduction

Kaneo is a modern, self-hosted project management and kanban board application designed for teams and individuals who want full control over their workflow data. With an intuitive drag-and-drop interface, Kaneo makes it easy to organize tasks, track progress, and collaborate effectively.

Built with modern web technologies, Kaneo offers a clean, responsive interface that works seamlessly across devices. Whether you’re managing personal projects or coordinating team workflows, Kaneo provides the tools you need without the complexity of enterprise solutions.

Key highlights of Kaneo:

• Kanban Boards: Visual task management with customizable columns and swimlanes
• Drag and Drop: Intuitive interface for moving tasks between stages
• Multiple Projects: Organize work across multiple boards and projects
• Task Details: Rich task cards with descriptions, due dates, labels, and attachments
• Team Collaboration: Share boards with team members and assign tasks
• Filters and Search: Quickly find tasks with powerful filtering options
• Activity Tracking: View task history and recent changes
• Mobile Responsive: Full functionality on any device
• Real-Time Updates: See changes instantly across all connected clients
• Self-Hosted: Complete data ownership and privacy

This guide walks through deploying Kaneo on Klutch.sh using Docker, configuring your workspace, and setting up the application for team productivity.

Why Deploy Kaneo on Klutch.sh

Deploying Kaneo on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kaneo without complex configuration.

Persistent Storage: Attach persistent volumes for your database and file uploads. Your projects and tasks survive restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your project management tools.

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on team size and usage patterns.

Environment Variable Management: Securely store database credentials and secret keys through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your Kaneo instance for easy team access.

Always-On Availability: Your project boards remain accessible 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Kaneo configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain for your Kaneo instance

Understanding Kaneo Architecture

Kaneo uses a modern web application architecture:

Frontend: A responsive single-page application providing the kanban board interface.

Backend API: RESTful API handling board operations, user management, and real-time updates.

Database: Persistent storage for boards, tasks, users, and activity history.

File Storage: Storage for task attachments and uploaded files.

WebSocket: Real-time communication for instant updates across clients.

Preparing Your Repository

To deploy Kaneo on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

kaneo-deploy/
├── Dockerfile
├── .env.example
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Install dependencies
RUN apk add --no-cache python3 make g++

# Create app directory
WORKDIR /app

# Clone Kaneo
RUN apk add --no-cache git && \
    git clone https://github.com/kaneo/kaneo.git . && \
    apk del git

# Install dependencies
RUN npm install

# Build application
RUN npm run build

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

# Expose web interface
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["npm", "start"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	Database connection string
SECRET_KEY	Yes	-	Application secret for sessions
PORT	No	3000	Web server port
NODE_ENV	No	production	Node.js environment

Deploying Kaneo on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Generate a Secret Key

Generate a secure secret key:

openssl rand -hex 32

Save this securely for environment variable configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Kaneo deployment configuration"
git remote add origin https://github.com/yourusername/kaneo-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 “kaneo” or “project-management”.

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 Kaneo Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

In the environment variables section, add:

Variable	Value
SECRET_KEY	Your generated secret key
NODE_ENV	production

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/data	5 GB	Database and application data
/app/uploads	10 GB	File attachments and uploads

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 Kaneo container
• Provision an HTTPS certificate

Access Kaneo

Once deployment completes, access your Kaneo instance at https://example-app.klutch.sh. Create your admin account during first setup.

Initial Setup and Configuration

Creating Your First Board

After registration:

1. Click Create Board on the dashboard
2. Enter a board name and description
3. Choose a color or icon for easy identification
4. Click Create

Customizing Columns

Set up your workflow stages:

1. Open your board
2. Click the column settings icon
3. Add, rename, or remove columns
4. Common setups: To Do, In Progress, Review, Done

Creating Tasks

Add tasks to your board:

1. Click Add Task in any column
2. Enter task title and description
3. Set due date if applicable
4. Add labels for categorization
5. Assign team members

Using Labels

Organize tasks with color-coded labels:

1. Access board settings
2. Create custom labels (Bug, Feature, Priority, etc.)
3. Apply labels to tasks for visual organization
4. Filter board view by labels

Team Collaboration

Inviting Team Members

Share your boards:

1. Open board settings
2. Click Invite Members
3. Enter email addresses
4. Set permission levels (View, Edit, Admin)
5. Send invitations

Task Assignment

Assign work to team members:

1. Open task details
2. Click Assign
3. Select team members
4. Assignees receive notifications

Activity Feed

Track project progress:

1. View recent activity on the board
2. See who made changes and when
3. Monitor task movements between columns
4. Review comments and updates

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce strong passwords for all users
• HTTPS Only: Always access Kaneo over HTTPS
• Regular Backups: Back up your database regularly
• Access Control: Review board permissions periodically
• Update Regularly: Keep Kaneo updated for security patches

Performance Optimization

• Database Indexing: Ensure proper database indexes for large boards
• Archive Old Boards: Archive completed projects to improve performance
• Resource Allocation: Scale resources based on team size
• CDN Integration: Consider CDN for file attachments

Backup Strategy

Protect your project data:

1. Database Backups: Regularly back up the database
2. File Backups: Back up uploaded attachments
3. Export Boards: Use any export functionality for local backups
4. Automated Scheduling: Set up automated backup routines

Troubleshooting Common Issues

Board Not Loading

Symptoms: Board displays loading state indefinitely.

Solutions:

• Check browser console for JavaScript errors
• Verify WebSocket connections are working
• Clear browser cache and reload
• Review application logs for errors

Tasks Not Saving

Symptoms: Changes to tasks revert or don’t persist.

Solutions:

• Check database connectivity
• Verify persistent volume is correctly mounted
• Review disk space availability
• Check application logs for database errors

Real-Time Updates Not Working

Symptoms: Changes by other users don’t appear.

Solutions:

• Verify WebSocket support is enabled
• Check network connectivity
• Refresh the page to re-establish connection
• Review WebSocket logs for errors

Additional Resources

• Kaneo GitHub Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Kaneo on Klutch.sh gives you a powerful, self-hosted project management solution with modern kanban boards. The combination of Kaneo’s intuitive interface and Klutch.sh’s deployment simplicity means you can focus on your projects rather than infrastructure.

With drag-and-drop task management, team collaboration features, and real-time updates, Kaneo provides everything needed for effective project tracking. Whether you’re managing personal tasks or coordinating team workflows, Kaneo on Klutch.sh offers a reliable, always-available platform that you control.