Deploying UBOS

Introduction

UBOS (pronounced “you-boss”) is a Linux distribution specifically designed to make self-hosting personal servers dramatically simpler. Instead of manually configuring each application, UBOS provides a declarative model where you describe what you want, and the system handles the complex details of installation, configuration, and maintenance.

Built on Arch Linux, UBOS abstracts away the complexity of server administration with a focus on personal clouds, websites, and web applications. It handles tasks like SSL certificates, database setup, backup, and upgrades automatically, letting you focus on using your applications rather than maintaining them.

Key highlights of UBOS:

One-Command Deployment: Deploy complex web applications with a single command
Automatic SSL: Let’s Encrypt integration for free SSL certificates
Backup and Restore: Built-in backup system for all applications
Easy Updates: Update all applications and the OS with one command
Site Management: Host multiple sites and applications per server
Database Automation: Automatic database provisioning and configuration
Container Support: Run applications in containers when needed
Hardware Flexibility: Run on Raspberry Pi, VMs, cloud instances, or bare metal
Open Source: Fully open-source with community support

This guide walks through deploying UBOS on Klutch.sh using Docker, understanding its unique deployment model, and managing applications.

Why Deploy UBOS on Klutch.sh

Deploying UBOS on Klutch.sh provides several advantages for personal server hosting:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds UBOS without complex configuration. Push to GitHub, and your personal server deploys automatically.

Persistent Storage: Attach persistent volumes for your applications and data. Your sites and data survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates at the infrastructure level, complementing UBOS’s own certificate management.

Always-On Availability: Your personal server remains accessible 24/7 without managing your own hardware.

Scalable Resources: Allocate CPU and memory based on your application needs.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your UBOS configuration
Basic familiarity with Linux and containerization concepts
(Optional) A custom domain for your UBOS server

Understanding UBOS Architecture

UBOS is built on several key concepts:

Sites: Logical groupings of applications at a particular hostname (e.g., example.com).

AppConfigurations: Individual application installations within a site.

Accessories: Optional add-ons that enhance application functionality.

Backup: Integrated backup and restore for complete disaster recovery.

The UBOS tools (ubos-admin) handle all the orchestration between applications, databases, and web servers.

Preparing Your Repository

To deploy UBOS on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

ubos-deploy/
├── Dockerfile
├── site-config/
│   └── site.json
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM archlinux:latest

# Update system and install UBOS tools
RUN pacman -Syu --noconfirm \
    && pacman -S --noconfirm wget curl

# Add UBOS repository
RUN echo '[ubos]' >> /etc/pacman.conf \
    && echo 'Server = https://depot.ubos.net/yellow/$arch/main' >> /etc/pacman.conf

# Import UBOS key and install
RUN pacman-key --init \
    && pacman-key --recv-keys 03E2B766
    && pacman -Sy --noconfirm ubos-admin

# Create data directories
RUN mkdir -p /ubos/data /ubos/backup

# Copy site configuration
COPY site-config/ /site-config/

# Expose web ports
EXPOSE 80 443

# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

# Start UBOS
CMD ["ubos-admin", "start"]

Site Configuration

Create site-config/site.json for your initial site setup:

{
    "hostname": "your-domain.klutch.sh",
    "siteid": "s1234567890",
    "admin": {
        "userid": "admin",
        "username": "Administrator",
        "credential": "${ADMIN_PASSWORD}",
        "email": "admin@example.com"
    },
    "appconfigs": [
        {
            "appid": "nextcloud",
            "context": ""
        }
    ]
}

Environment Variables Reference

Variable	Required	Default	Description
`ADMIN_PASSWORD`	Yes	-	Password for the admin user
`HOSTNAME`	Yes	-	Hostname for the UBOS site

Deploying UBOS on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile site-config/ .dockerignore
git commit -m "Initial UBOS deployment configuration"
git remote add origin https://github.com/yourusername/ubos-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 “ubos” or “personal-server”.

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

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80 (web server port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
`ADMIN_PASSWORD`	A secure admin password
`HOSTNAME`	`your-app-name.klutch.sh`

Attach Persistent Volumes

Persistent storage is essential for UBOS. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/ubos/data`	20+ GB	Application data and databases
`/ubos/backup`	10 GB	Backup storage
`/var/lib/mysql`	5 GB	MySQL database files

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

Access UBOS

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

Managing Sites

Creating a Site

Deploy a new site with applications:

ubos-admin createsite

Follow the interactive prompts to:

Enter hostname
Select applications to install
Configure admin credentials
Complete setup

Listing Sites

View all deployed sites:

ubos-admin listsites

Site Information

Get details about a specific site:

ubos-admin showsite --hostname example.com

Available Applications

UBOS includes many popular applications:

Nextcloud: File sync and collaboration
WordPress: Blogging and websites
Mastodon: Federated social network
MediaWiki: Wiki platform
Webtrees: Genealogy software
Selfoss: RSS reader
And many more

Installing Applications

Add applications to a site:

ubos-admin createsite --hostname example.com \
  --app nextcloud --context /cloud \
  --app wordpress --context /blog

Listing Available Apps

See all available applications:

ubos-admin listapps

Backup and Restore

Creating Backups

Back up your site:

ubos-admin backup --hostname example.com --backuptofile /ubos/backup/site-backup.ubos-backup

Automated Backups

Set up scheduled backups in your configuration.

Restoring from Backup

Restore a site from backup:

ubos-admin restore --in /ubos/backup/site-backup.ubos-backup

Updating UBOS

System Updates

Update everything at once:

ubos-admin update

This updates:

Operating system packages
All installed applications
Databases and configurations

Checking for Updates

See available updates:

ubos-admin showupdates

SSL Certificates

Automatic Certificates

UBOS can manage Let’s Encrypt certificates. However, since Klutch.sh provides SSL at the edge, you typically won’t need UBOS’s certificate management.

Certificate Configuration

If needed, configure certificates:

ubos-admin setuptls --hostname example.com

Production Best Practices

Backup Strategy

Schedule regular automated backups
Store backups on persistent volumes
Test restore procedures periodically
Keep multiple backup generations

Security

Use strong admin passwords
Keep UBOS updated regularly
Monitor application security advisories
Limit unnecessary applications

Resource Management

Monitor disk space usage
Scale resources based on application needs
Remove unused applications

Troubleshooting Common Issues

Application Not Starting

Symptoms: Site shows errors or is unavailable.

Solutions:

Check UBOS status: ubos-admin status
Review logs: journalctl -xe
Verify database connectivity
Check disk space

Update Failures

Symptoms: Updates don’t complete successfully.

Solutions:

Check network connectivity
Verify disk space
Review update logs
Restore from backup if needed

Backup Issues

Symptoms: Backups fail or are incomplete.

Solutions:

Verify backup volume has space
Check file permissions
Review backup logs

Additional Resources

Conclusion

Deploying UBOS on Klutch.sh gives you a simplified personal server platform accessible from anywhere. The combination of UBOS’s one-command deployments and Klutch.sh’s infrastructure automation means you can host multiple applications without server administration expertise.

With integrated backup, automatic updates, and a growing application library, UBOS provides everything you need for self-hosted personal services. Your data remains under your control on reliable, always-available infrastructure.