Deploying Usertour

Introduction

Usertour is an open-source user onboarding platform that enables you to create interactive product tours, tooltips, and checklists without writing code. Self-hosted and privacy-focused, Usertour helps improve user adoption and feature discovery through guided experiences.

Key highlights of Usertour:

• No-Code Builder: Create tours and guides with a visual drag-and-drop editor
• Product Tours: Build multi-step walkthroughs to onboard new users
• Tooltips: Add contextual help and hints throughout your application
• Checklists: Guide users through setup processes with task completion tracking
• User Segmentation: Target specific user groups with personalized experiences
• Analytics: Track tour completion rates and user engagement metrics
• Self-Hosted: Full control over your data and user information
• JavaScript SDK: Easy integration with any web application

This guide walks through deploying Usertour on Klutch.sh using Docker, configuring the platform, and integrating it with your applications.

Why Deploy Usertour on Klutch.sh

Deploying Usertour on Klutch.sh provides several advantages for user onboarding:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Usertour without complex orchestration. Push to GitHub, and your onboarding platform deploys automatically.

Persistent Storage: Attach persistent volumes for your database and assets. Your tours, user data, and analytics survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure communication between your application and the Usertour backend.

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

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

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Usertour configuration
• Basic familiarity with Docker and containerization concepts
• A web application where you want to implement user onboarding

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Usertour deployment.

Repository Structure

usertour-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM usertour/usertour:latest

# Set environment variables
ENV DATABASE_URL=${DATABASE_URL}
ENV SECRET_KEY=${SECRET_KEY}
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}

# Expose the web interface port
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

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
SECRET_KEY	Yes	-	Secret key for session encryption
NEXT_PUBLIC_API_URL	Yes	-	Public URL of your Usertour instance

Deploying Usertour on Klutch.sh

Set Up PostgreSQL Database

Usertour requires a PostgreSQL database. Deploy a PostgreSQL instance on Klutch.sh or use an external database service.

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “usertour” or “onboarding-platform”.

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
DATABASE_URL	postgresql://user:password@host:5432/usertour
SECRET_KEY	Your generated secret key
NEXT_PUBLIC_API_URL	https://your-app-name.klutch.sh

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
/app/data	5 GB	Application data and uploads

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access Usertour

Once deployment completes, access your Usertour instance at https://your-app-name.klutch.sh. Create an admin account on first access.

Creating Your First Tour

Setting Up a Project

1. Log in to your Usertour dashboard
2. Create a new project for your application
3. Copy the provided JavaScript snippet
4. Add the snippet to your application’s HTML

Building a Product Tour

1. Navigate to Tours in the dashboard
2. Click Create Tour to start a new tour
3. Use the visual editor to add steps
4. Configure triggers (e.g., first visit, button click)
5. Preview and publish your tour

Adding Tooltips

1. Go to Tooltips section
2. Create a new tooltip with target element selector
3. Add helpful content and positioning
4. Set display conditions and save

Integration Example

Add Usertour to your web application:

<script>
  (function(u,s,e,r,t,o,u,r){
    // Usertour initialization code
    // Replace with your actual snippet from the dashboard
  })();
</script>

Additional Resources

• Usertour GitHub Repository
• Usertour Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Usertour on Klutch.sh gives you a powerful, self-hosted user onboarding platform with full control over your data. The combination of Usertour’s no-code builder and Klutch.sh’s deployment simplicity means you can quickly improve user adoption and feature discovery in your applications.