Onboarding Overview
Welcome to RunOS! The onboarding process helps you get up and running quickly, whether you're new to hosting platforms or an experienced developer. This guide explains how to access and navigate the onboarding experience.
What is Onboarding?
The RunOS onboarding is a guided experience that walks you through:
- Adding your first server to the platform
- Configuring your Kubernetes cluster with essential services
- Deploying databases like MySQL or PostgreSQL
- Launching marketplace applications such as WordPress or Vaultwarden
The entire process typically takes 15-30 minutes, depending on which steps you complete.
When Does Onboarding Appear?
The onboarding experience appears in two scenarios:
Automatic Access
When you create a new RunOS account and access your first cluster, you'll be taken directly to the onboarding welcome page.
Manual Access
You can access the onboarding at any time:
- Click the cluster selector dropdown in the top navigation
- Scroll to the bottom of the dropdown menu
- Select "Onboarding"
This allows you to revisit the guided setup or explore features you might have skipped initially.
Three Paths to Get Started
When you arrive at the onboarding welcome page, you'll see three options:
1. I Know What I'm Doing
Best for: Experienced users familiar with hosting platforms or Kubernetes
This path takes you directly to the main console where you can:
- Access all features immediately
- Configure your cluster manually
- Deploy services without guided assistance
Navigation: Takes you straight to the Nodes page to begin adding servers.
2. I'm New to This (Recommended)
Best for: First-time users or anyone who wants step-by-step guidance
This path provides a guided onboarding flow that walks you through:
- Adding your first server
- Configuring essential cluster services
- Deploying databases and applications
- Understanding key concepts along the way
Navigation: Starts the guided flow with an interactive dashboard showing your progress.
3. Read the Docs
Best for: Users who prefer to learn by reading comprehensive documentation
This path opens the RunOS documentation in a new tab, where you can:
- Explore detailed guides and tutorials
- Understand platform architecture
- Learn best practices at your own pace
Navigation: Opens the documentation in a new browser tab.
The Guided Onboarding Dashboard
When you choose "I'm new to this," you'll see a dashboard with interactive cards representing each setup step.
Dashboard Features
Visual Progress Tracking: Each card shows its current state with visual indicators:
- Green cards - Ready to start, click to begin
- Gray cards - Prerequisites not met, locked until requirements are satisfied
- Blue checkmark - Already completed
Live Status Updates: The dashboard displays real-time information:
- Number of servers online
- Cluster configuration status
- Progress through your setup journey
Flexible Navigation: From any step, you can:
- Return to the onboarding dashboard
- Skip to the main console
- Access documentation
Onboarding Steps
The guided flow includes these steps:
Step 1: Add Servers
Status: Always available
Add your first server to RunOS. You can choose between:
- Self-managed setup - Add an existing server you control
- Automatic cloud provisioning - Let RunOS provision a cloud server (Hetzner supported)
Time required: 5-10 minutes
Step 2: Configure Cluster
Status: Unlocked when at least one server is online
Transform your server into a fully configured Kubernetes cluster. This installs:
- OpenEBS storage for persistent data
- Cert-manager for automatic SSL certificates
- Metrics server for monitoring
- Traefik ingress for routing traffic
- RunOS cluster agent for management
Time required: 1-5 minutes
Step 3: Deploy MySQL Database
Status: Unlocked when cluster is configured
Deploy a production-ready MySQL database with:
- MySQL 8.0 with intelligent defaults
- Prometheus and Grafana monitoring
- SSL/TLS encryption
- Secure connection credentials
Time required: 1-5 minutes
Step 4: Deploy PostgreSQL Database
Status: Unlocked when cluster is configured
Deploy a production-ready PostgreSQL database with:
- PostgreSQL 15 with advanced features
- Prometheus and Grafana monitoring
- SSL/TLS encryption
- Secure connection credentials
Time required: 1-5 minutes
Step 5: Deploy Marketplace App
Status: Unlocked when cluster is configured
Deploy popular pre-configured applications:
- WordPress - Content management system
- Vaultwarden - Self-hosted password manager
- OpenProject - Project management platform
Each app includes automatic SSL, domain configuration, and persistent storage.
Time required: 1-3 minutes
Step 6: Read Documentation
Status: Always available
Quick access to comprehensive documentation throughout your onboarding journey.
Progressive Unlocking
The guided onboarding uses a dependency system to ensure proper setup sequence:
Add Servers
↓ (requires 1+ servers)
Configure Cluster
↓ (requires configured cluster)
Deploy Services & Applications
Steps unlock automatically as you meet prerequisites. This ensures you don't deploy services before your cluster is ready.
Flexibility and Control
The onboarding experience is designed to be flexible:
- No commitment required - Switch between guided and manual modes at any time
- Skip anytime - Every guided page includes a "Skip to Console" button
- Return later - Access the onboarding flow again from the cluster selector dropdown
- Non-blocking - Skipping doesn't prevent you from accessing any features
- Stateful progress - The dashboard tracks your cluster's actual state
State Persistence
When you return to onboarding after initial setup:
Dashboard reflects current state:
- "Add Servers" shows current server count badge (e.g., "3 online")
- "Configure Cluster" displays as "Done" if already configured
- All steps show accurate status based on your cluster
No data loss:
- Existing configurations remain unchanged
- Previously deployed services continue running
- No data is deleted or modified
Idempotent steps: Some steps can be safely repeated:
- Add Servers (add more servers anytime)
- Deploy MySQL (deploy additional instances)
- Deploy PostgreSQL (deploy additional instances)
- Deploy Apps (deploy more applications)
One-time steps:
- Configure Cluster (once complete, cannot be re-run to prevent breaking changes)
Quick Reference
Time Estimates
| Step | Time Required |
|---|---|
| Add Server | 5-10 minutes |
| Configure Cluster | 1-5 minutes |
| Deploy MySQL | 1-5 minutes |
| Deploy PostgreSQL | 1-5 minutes |
| Deploy Marketplace App | 1-3 minutes |
| Total (full flow) | 15-30 minutes |
Common Paths
Fastest Start (10-15 minutes):
- Add 1 server
- Configure cluster
- Skip to console
Database Setup (15-20 minutes):
- Add 1 server
- Configure cluster
- Deploy MySQL or PostgreSQL
- Skip to console
Full Experience (20-30 minutes):
- Add 1 server
- Configure cluster
- Deploy databases
- Deploy a marketplace app
- Explore console
Tips for Success
- Don't rush - Wait for each step to complete before moving on
- Save credentials - Copy database and application credentials immediately
- Watch progress - Real-time progress modals show what's happening
- Use defaults - Onboarding provides production-ready configurations
- Start small - Begin with one server, add more later
- Return anytime - Onboarding accessible via cluster selector dropdown
- Skip if needed - No requirement to complete all steps
What Happens Next?
After completing the onboarding:
Immediate Actions
- Save credentials - Store all database and app passwords securely
- Bookmark URLs - Save your application URLs for easy access
- Explore console - Navigate to see your cluster
- Check monitoring - Access Grafana dashboards for metrics
Next Steps
- Deploy custom applications from Git repositories
- Add more servers for high availability
- Configure backups for databases
- Set up custom domains
- Invite team members
- Explore additional services
When to Use Onboarding vs Manual Configuration
Use Onboarding When:
- Setting up a new cluster from scratch
- You want automated, best-practice configurations
- Deploying common services (MySQL, PostgreSQL, WordPress)
- You prefer guided workflows with progress tracking
- Training new team members
- You want to see deployment time estimates
Use Manual Configuration When:
- Deploying custom or advanced services
- You need specific configuration parameters
- Deploying services not in the onboarding flow
- You require custom Kubernetes manifests
- Working with existing infrastructure as code
- Integrating with external systems
Troubleshooting
Server Won't Come Online
- Verify Ubuntu version compatibility
- Check firewall rules allow outbound connections
- Ensure installation command completed successfully
- Wait 2-3 minutes for agent to register
Cluster Configuration Fails
- Check server has adequate resources (2GB+ RAM recommended)
- Verify internet connectivity on server
- Review error messages in progress modal
- Contact support if issue persists
Can't Access Deployed Services
- Verify DNS has propagated (can take a few minutes)
- Check SSL certificate was issued successfully
- Try accessing via internal cluster hostname first
- Review service logs in console
Lost Credentials
- Database credentials shown once at deployment completion
- Access service details in console under "Services"
- Can reset passwords through console interface
- Contact support for credential recovery assistance
Ready to get started? Access your onboarding dashboard and begin your RunOS journey!