Codakey
Play
← Back to yunohost

How to Deploy & Use yunohost

YunoHost Deployment and Usage Guide

1. Prerequisites

Hardware Requirements

  • A dedicated server or virtual private server (VPS)
  • Minimum 1GB RAM (2GB+ recommended)
  • 10GB+ disk space
  • x86_64 architecture (ARM support is experimental)

Network Requirements

  • A public IP address
  • A domain name (or subdomain) pointing to your server's IP
  • Ports 80 (HTTP) and 443 (HTTPS) must be open
  • Port 25 (SMTP) recommended for email functionality

Software Requirements

YunoHost is typically installed as a complete operating system, but for development:

  • Debian 11 "Bullseye" or newer (YunoHost is based on Debian)
  • Python 3.9+
  • Bash shell
  • Git for source code management

2. Installation

Standard Installation (Production)

YunoHost is designed to be installed as a complete OS. Choose one of these methods:

Method 1: Direct installation on bare metal/VPS

# Download the latest YunoHost ISO from:
# https://yunohost.org/#/download

# Burn to USB/DVD or mount in your virtualization software
# Boot from the media and follow the graphical installer

Method 2: Install on existing Debian 11+ system

# Install curl if not present
sudo apt update && sudo apt install curl

# Run the installation script
curl https://install.yunohost.org | bash

Method 3: Using the official installer

wget -O yunohost_install.sh https://install.yunohost.org/
sudo bash yunohost_install.sh

Development Installation (From Source)

For contributing to YunoHost core development:

# Clone the repository
git clone https://github.com/YunoHost/yunohost.git
cd yunohost

# Install system dependencies
sudo apt update
sudo apt install python3-pip python3-venv python3-dev build-essential \
                 libssl-dev libffi-dev git

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

# Note: Full YunoHost functionality requires running as root
# and additional system packages installed via apt

3. Configuration

Post-Installation Setup

After installation, access your server via SSH or the web interface:

  1. Initial Configuration:

    # Run post-installation (if not done during install)
sudo yunohost tools postinstall

  2. Configure Domain:

    # Add your primary domain
sudo yunohost domain add example.com

  3. Set Admin Password:

    # Change root/admin password
sudo yunohost tools rootpw "your_secure_password"

Important Configuration Files

  • /etc/yunohost/: Main configuration directory
  • /etc/yunohost/settings.yml: System settings
  • /etc/yunohost/permissions.yml: Permission system configuration
  • /etc/yunohost/migrations.yaml: Migration state tracking
  • /etc/yunohost/domains/: Domain-specific configurations
  • /var/log/yunohost/operations/: Operation logs

DNS Configuration

YunoHost provides DNS suggestions for your domain:

# Get DNS records to configure at your registrar
sudo yunohost domain dns suggestion example.com

Typical DNS records needed:

  • A record pointing to your server's IP
  • CNAME for www subdomain
  • MX records for email
  • TXT records for SPF, DKIM, DMARC

4. Build & Run

Development Environment

For working on YunoHost core:

# Activate development environment
source venv/bin/activate

# Run YunoHost commands (some require sudo)
sudo yunohost --help

# Test specific modules
python3 -m pytest src/tests/

# Check code quality
python3 -m black --check src/
python3 -m flake8 src/

Running Services

YunoHost manages several services automatically:

# Check system status
sudo yunohost tools status

# View running services
sudo systemctl list-units | grep yunohost

# Restart YunoHost core services
sudo systemctl restart yunohost-api
sudo systemctl restart nginx

Web Interfaces

After installation, access:

  • Web Admin: https://your-domain.tld/yunohost/admin
  • User Portal: https://your-domain.tld
  • SSO Portal: https://your-domain.tld

5. Deployment

Deployment Platforms

YunoHost works best on:

Recommended:

  • Dedicated servers (OVH, Online.net, Hetzner)
  • VPS providers (DigitalOcean, Linode, Vultr, Scaleway)
  • Self-hosted on physical hardware

Cloud Platforms:

  • Any provider offering Debian 11+ images
  • Can be deployed on OpenStack, Proxmox, VMware

Special Notes:

  • Avoid shared hosting (requires full system access)
  • Check provider allows opening required ports
  • Some cloud providers block port 25 (email)

Deployment Checklist

  1. Server Setup:

    • Install Debian 11+ minimal
    • Configure SSH access
    • Set up firewall (allow 22, 80, 443, 25)

  2. Domain Preparation:

    • Purchase domain name
    • Point DNS to server IP (or use dynamic DNS)
    • Allow time for propagation

  3. YunoHost Installation:

    # Use the automated installer
curl https://install.yunohost.org | bash

# Follow interactive prompts

  4. Post-Deployment:

    • Configure SSL certificates (Let's Encrypt auto-configured)
    • Set up backup strategy
    • Configure email (if needed)
    • Install desired applications

Backup and Migration

# Create backup
sudo yunohost backup create --system apps

# List backups
sudo yunohost backup list

# Restore from backup
sudo yunohost backup restore backup_name

6. Troubleshooting

Common Issues

Issue: Installation fails

# Check logs
sudo tail -f /var/log/yunohost/yunohost-cli.log
sudo journalctl -u yunohost-installation -f

# Verify system requirements
lsb_release -a  # Should be Debian 11+
free -h         # Check RAM
df -h           # Check disk space

Issue: DNS problems

# Check DNS propagation
dig example.com
dig example.com MX

# Regenerate DNS suggestions
sudo yunohost domain dns suggestion example.com --force

Issue: Web interface not accessible

# Check nginx status
sudo systemctl status nginx

# Check firewall
sudo iptables -L -n

# Test locally
curl -k https://localhost

Issue: Permission errors

# Check permission system
sudo yunohost permission list

# Rebuild permission system
sudo yunohost permission rebuild

Issue: Broken packages

# Check for broken packages
sudo dpkg --configure -a
sudo apt --fix-broken install

# Update YunoHost
sudo yunohost tools update

Log Files Location

  • /var/log/yunohost/: Main log directory
  • /var/log/yunohost/operations/: Individual operation logs
  • /var/log/nginx/: Web server logs
  • /var/log/mysql/: Database logs (if applicable)
  • /var/log/yunohost/yunohost-cli.log: CLI operations

Getting Help

Debug Mode

# Enable debug logging
export YUNOHOST_DEBUG=1

# Run commands with verbose output
sudo yunohost --debug domain list

# Check migration state
cat /etc/yunohost/migrations.yaml

System Recovery

# Boot in recovery mode (if available)
# Access via SSH or console

# Repair disk issues
sudo fsck -y /dev/sda1

# Reinstall core packages
sudo apt install --reinstall yunohost

# Restore from backup
sudo yunohost backup restore latest
← Project overviewView alternatives to yunohost →