Deploying Tipi

Introduction

Tipi is a personal homeserver management platform that simplifies self-hosting by providing a beautiful web interface for deploying and managing applications. With Tipi, you can spin up popular open-source applications with just a few clicks, without needing deep knowledge of Docker, networking, or system administration.

Think of Tipi as your personal app store for self-hosted software. It curates a collection of pre-configured applications ranging from media servers to productivity tools, each packaged for easy deployment with sensible defaults.

Key highlights of Tipi:

• One-Click App Installation: Deploy popular self-hosted apps without manual configuration
• Curated App Store: Growing collection of pre-configured applications
• Automatic Updates: Keep apps updated with built-in update management
• Reverse Proxy Integration: Built-in Traefik for automatic SSL and routing
• Resource Monitoring: Track CPU, memory, and storage usage
• User Management: Multi-user support with role-based permissions
• Backup System: Built-in backup and restore functionality
• Custom Apps: Add your own applications to the platform
• Modern Interface: Clean, responsive dashboard for management
• 100% Open Source: Licensed under GPL-3.0

This guide walks through deploying Tipi on Klutch.sh using Docker, exploring the app store, and managing your self-hosted applications.

Why Deploy Tipi on Klutch.sh

Deploying Tipi on Klutch.sh provides several advantages:

Managed Infrastructure: Run your homeserver platform without managing physical hardware or dealing with ISP limitations.

Reliable Connectivity: Klutch.sh provides stable networking without port forwarding or dynamic DNS concerns.

HTTPS by Default: Automatic SSL certificates for secure access to your Tipi dashboard and managed apps.

Scalable Resources: Start small and scale up as you add more applications to your homeserver.

GitHub Integration: Manage your Tipi configuration through version control with automatic redeployments.

Persistent Storage: Your app data and configurations persist across restarts and updates.

Prerequisites

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

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

Understanding Tipi Architecture

Tipi uses a layered architecture for managing applications:

Dashboard: A React-based web interface for browsing and managing applications.

Backend API: Node.js/TypeScript API handling app installations, updates, and system operations.

Traefik Reverse Proxy: Automatic routing and SSL termination for installed applications.

Docker Engine: Apps are deployed as Docker containers managed by Tipi.

App Repository: A curated collection of Docker Compose configurations for each available app.

SQLite Database: Stores app configurations, user settings, and system state.

Preparing Your Repository

Create a GitHub repository with your Tipi configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/runtipi/runtipi:latest

# Set environment variables
ENV TIPI_HOST=0.0.0.0
ENV TIPI_PORT=80
ENV NODE_ENV=production

# Create data directories
RUN mkdir -p /runtipi/data /runtipi/app-data /runtipi/traefik

# Set working directory
WORKDIR /runtipi

# Expose ports
EXPOSE 80
EXPOSE 443

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

Creating the .dockerignore File

Create a .dockerignore file:

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

Deploying Tipi on Klutch.sh

Follow these steps to deploy your Tipi instance:

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Tipi configuration"
git remote add origin https://github.com/yourusername/tipi-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. Name it something like “homeserver” or “tipi”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Tipi repository.

Configure HTTP Traffic

Tipi serves its dashboard over HTTP. In the deployment settings:

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

Set Environment Variables

Configure environment variables:

Variable	Value
TIPI_DOMAIN	your-app-name.klutch.sh
TIPI_INTERNAL_IP	0.0.0.0
NODE_ENV	production

Attach Persistent Volumes

Add persistent storage for Tipi and its managed apps:

Mount Path	Recommended Size	Purpose
/runtipi/data	10 GB	Tipi configuration and database
/runtipi/app-data	100 GB	Data for all installed applications
/runtipi/traefik	1 GB	Traefik proxy configuration

Deploy Your Application

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

• Build your Docker image
• Attach persistent volumes
• Start the Tipi dashboard
• Provision an HTTPS certificate

Complete Initial Setup

Navigate to https://your-app-name.klutch.sh to complete the setup wizard:

1. Create your admin account
2. Configure basic settings
3. Explore the app store

Initial Configuration

Creating Your Admin Account

On first access, you’ll create an administrator account:

1. Enter your desired username
2. Set a strong password
3. Complete the setup wizard

Dashboard Overview

The Tipi dashboard provides:

• Home: System overview and quick actions
• Apps: Browse and manage installed applications
• App Store: Discover new applications to install
• Settings: System configuration and user management

Exploring the App Store

Available Categories

Tipi’s app store includes applications across categories:

Category	Example Apps
Media	Jellyfin, Plex, Navidrome
Productivity	Nextcloud, Vikunja, Bookstack
Development	Gitea, Code-Server, Portainer
Home Automation	Home Assistant, Node-RED
Security	Vaultwarden, Authelia
Communication	Matrix, Discourse
Monitoring	Uptime Kuma, Grafana

Installing Applications

To install an application:

1. Navigate to the App Store
2. Find the application you want
3. Click Install
4. Configure any required settings
5. Wait for the installation to complete

Managing Installed Apps

Starting and Stopping

Control app states through the dashboard:

1. Navigate to Apps
2. Select the application
3. Use the Start/Stop/Restart buttons

Updating Applications

Keep apps current:

1. Check for updates on the Apps page
2. Click Update when available
3. Tipi pulls the latest image and restarts the app

Viewing Logs

Access application logs:

1. Select the application
2. Click the Logs tab
3. View real-time or historical logs

Backup and Restore

Creating Backups

Back up your Tipi data:

1. Navigate to Settings > Backups
2. Click Create Backup
3. Wait for the backup to complete
4. Download the backup file

Restoring from Backup

Restore previous state:

1. Upload your backup file
2. Select what to restore
3. Confirm and restore

User Management

Adding Users

Create additional users:

1. Go to Settings > Users
2. Click Add User
3. Set username, password, and role

User Roles

Role	Capabilities
Admin	Full system access
User	App access, limited settings
Guest	View-only access

Performance Tuning

Resource Recommendations

Apps Installed	RAM	CPU	Storage
1-5	2 GB	1 vCPU	50 GB
5-10	4 GB	2 vCPU	100 GB
10+	8 GB	4 vCPU	200 GB+

Troubleshooting Common Issues

Dashboard Not Loading

Symptoms: Blank page or connection errors.

Solutions:

• Verify the container is running
• Check port 80 configuration
• Review startup logs for errors

App Installation Fails

Symptoms: Apps fail to install or start.

Solutions:

• Check available disk space
• Review app-specific logs
• Ensure required ports are available

Additional Resources

• Official Tipi Website
• Tipi Documentation
• Tipi GitHub Repository
• Tipi App Store Repository
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Tipi on Klutch.sh provides an accessible entry point to self-hosting, combining a beautiful management interface with Klutch.sh’s reliable infrastructure. The curated app store removes the complexity of researching and configuring individual applications, letting you focus on using the software rather than deploying it.

Whether you’re new to self-hosting or looking for a more organized approach to managing your applications, Tipi provides the tools to build your personal cloud with minimal friction.