> For the complete documentation index, see [llms.txt](https://redcloud-os.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://redcloud-os.gitbook.io/docs/getting-started/installation.md).

# Installation Guide

### Overview

RedCloud OS can run in two modes:

* **Live Mode**: Boot from USB, no installation required (ephemeral)
* **Installed Mode**: Permanent installation to disk (persistent)

This guide focuses on permanent installation for users who want:

* Persistent configuration and data
* Daily security workstation
* Long-term tooling environment
* System customization

### Before You Install

#### System Requirements

**Minimum**:

* CPU: AMD64-bit processor (2+ cores)
* RAM: 4GB
* Disk: 20GB+ free space
* Graphics (optional): Any GPU with 1024x768+ resolution

**Recommended**:

* CPU: AMD64-bit x86 processor (4+ cores)
* RAM: 8GB+
* Disk: 50GB+ SSD
* Graphics: Any modern GPU
* Network: Ethernet or WiFi

#### Supported Architectures

* [x] **amd64** (Intel/AMD 64-bit) - Fully supported
* [ ] **arm64** - Upcoming

#### Preparation Checklist

* [ ] Download RedCloud OS ISO
* [ ] Verify ISO checksum
* [ ] Create bootable USB (see Getting Started)
* [ ] **Backup important data** - Installation will erase target disk
* [ ] Ensure stable internet connection
* [ ] Disable Secure Boot in UEFI settings
* [ ] Allocate disk space (minimum 20GB)

### Installation Methods

#### Method 1: Guided Installation with Calamares (Recommended)

Easiest method with graphical installer.

#### Method 2: Manual Partitioning

For advanced users who want custom partition layouts.

#### Method 3: Dual Boot Setup

Install alongside existing operating systems.

***

### Method 1: Guided Installation

#### Step 1: Boot the ISO

1. Insert USB drive or load ISO in VM
2. Restart computer
3. Enter BIOS/UEFI and select USB/CD as boot device
4. Choose "RedCloud OS Live (amd64)" from GRUB menu
5. Wait for system to boot to desktop

#### Step 2: Launch Calamares Installer

Once logged into the live session:

**Option A**: Click the "Install RedCloud OS" icon on desktop

**Option B**: Application Menu → System → Install System

**Option C**: Terminal command:

```bash
sudo calamares
```

#### Step 3: Welcome Screen

* Select your language
* Click "Next"

#### Step 4: Location Settings

* Select your timezone by clicking on the map or dropdown
* Region and zone will be set automatically
* Click "Next"

#### Step 5: Keyboard Layout

* Select your keyboard layout (e.g., English (US))
* Test in the text box to verify
* Click "Next"

#### Step 6: Partitioning

This is the most critical step.

**Erase Disk (Simplest)**

**Destroys all data on selected disk**

1. Select "Erase disk"
2. Choose target disk from dropdown
3. Optionally enable encryption:
   * Check "Encrypt system"
   * Enter encryption passphrase
   * **Remember this passphrase** - you'll need it at every boot
4. Click "Next"

**Recommended for**:

* Single-boot installations
* VMs
* Dedicated security workstations

**Replace Partition**

Replace an existing OS while keeping other partitions:

1. Select "Replace a partition"
2. Choose the partition to replace
3. New RedCloud OS installation will use that space
4. Click "Next"

**Manual Partitioning**

See Method 2: Manual Partitioning below.

#### Step 7: User Account

Create your user account:

* **Your name**: Full name (e.g., "John Doe")
* **Username**: Login name (lowercase, no spaces)
* **Computer name**: Hostname (e.g., "redcloud-workstation")
* **Password**: Strong password for your account
* **Confirm password**: Re-enter password

**Options**:

* Log in automatically without asking for a password (not recommended)
* Use the same password for administrator account

::: tip Post-Install User This user replaces the live session user `redcloud`. After installation, the `redcloud` user is removed for security. :::

Click "Next"

#### Step 8: Summary

Review your installation choices:

* Language & timezone
* Keyboard layout
* Partitioning scheme
* User account

**Last chance to go back and make changes**

Click "Install" to proceed.

#### Step 9: Installation Progress

The installer will:

1. Format partitions
2. Copy system files (\~5-10 minutes)
3. Install bootloader (GRUB)
4. Configure system
5. Remove live session user
6. Set up your user account

**Do not turn off or restart the computer during installation.**

Progress indicators:

* Packages being installed
* Overall progress percentage
* Estimated time remaining

#### Step 10: Installation Complete

When installation finishes:

1. Click "Restart Now"
2. Remove USB drive when prompted
3. Press Enter to reboot

Your system will boot to the GRUB menu and then to the login screen.

#### Step 11: First Boot

1. **Login**: Use the username and password you created
2. **Welcome to RedCloud OS!**

***

### Method 2: Manual Partitioning

For advanced users who want control over disk layout.

#### Recommended Partition Scheme

**UEFI Systems**

| Mount Point | Size      | Type                 | Filesystem |
| ----------- | --------- | -------------------- | ---------- |
| `/boot/efi` | 512MB     | EFI System Partition | FAT32      |
| `/`         | 30GB+     | Root                 | ext4       |
| `/home`     | Remaining | Home                 | ext4       |
| `swap`      | 4-8GB     | Linux Swap           | swap       |

**Legacy BIOS Systems**

| Mount Point | Size      | Type       | Filesystem |
| ----------- | --------- | ---------- | ---------- |
| `/`         | 30GB+     | Root       | ext4       |
| `/home`     | Remaining | Home       | ext4       |
| `swap`      | 4-8GB     | Linux Swap | swap       |

#### Manual Partitioning Steps

1. In Calamares, select "Manual partitioning"
2. Click "New Partition Table" if starting fresh
3. Create partitions:

**EFI Partition** (UEFI only):

* Size: 512MB
* Type: EFI System Partition
* Filesystem: FAT32
* Mount point: `/boot/efi`
* Flags: `boot`, `esp`

**Root Partition**:

* Size: 30GB minimum (50GB+ recommended)
* Type: Primary
* Filesystem: ext4
* Mount point: `/`

**Home Partition** (optional but recommended):

* Size: Remaining space or desired size
* Type: Primary
* Filesystem: ext4
* Mount point: `/home`

**Swap Partition** (optional):

* Size: Same as RAM (for hibernation) or 4-8GB
* Type: Linux Swap
* Filesystem: swap
* Mount point: (none)

4. Click "Next" and continue with installation

***

### Method 3: Dual Boot Setup

Install RedCloud OS alongside Windows or other Linux distributions.

#### Prerequisites

* Existing OS installed
* Free disk space (20GB+ unallocated)
* Backup of existing OS

#### Windows Dual Boot

**Step 1: Prepare Windows**

**In Windows**:

1. **Disable Fast Startup**:
   * Control Panel → Power Options → Choose what the power buttons do
   * Change settings that are currently unavailable
   * Uncheck "Turn on fast startup"
2. **Shrink Windows Partition**:
   * Right-click Start → Disk Management
   * Right-click C: drive → Shrink Volume
   * Enter space to shrink (minimum 20000 MB)
   * Click Shrink
3. **Disable Secure Boot**:
   * Restart → Enter UEFI/BIOS
   * Find Secure Boot option
   * Disable it
   * Save and exit

**Step 2: Boot RedCloud ISO**

Boot from USB as normal.

**Step 3: Install Alongside**

In Calamares partitioning:

1. Select "Install alongside"
2. Choose Windows partition
3. Drag slider to allocate space
4. Minimum 20GB for RedCloud OS
5. Click "Next"

**Step 4: Bootloader**

Calamares will:

* Detect Windows Boot Manager
* Install GRUB bootloader
* Add Windows to GRUB menu

**Step 5: After Installation**

When you restart, you'll see GRUB menu:

```
RedCloud OS
Advanced options for RedCloud OS
Windows Boot Manager
UEFI Firmware Settings
```

Use arrow keys to select OS and press Enter.

#### Linux Dual Boot

Similar to Windows, but:

* Shrink Linux partition using GParted
* Install RedCloud to unallocated space
* GRUB will detect other Linux installations
* Both systems appear in GRUB menu

***

### Post-Installation Setup

#### First Login

1. Boot system
2. GRUB menu → Select RedCloud OS
3. SDDM login screen → Enter credentials
4. KDE Plasma desktop loads

#### Update System

```bash
# Update package lists
sudo apt update

# Upgrade installed packages
sudo apt upgrade -y
```

#### Install/update Tools

```bash
redcloud -u
or
redcloud --update
```

#### Configure Cloud Credentials

**AWS**

```bash
aws configure
# AWS Access Key ID: [your-key]
# AWS Secret Access Key: [your-secret]
# Default region name: us-east-1
# Default output format: json
```

**Azure**

```bash
az login
# Follow browser authentication flow
```

**GCP**

```bash
gcloud init
# Follow authentication steps
```

#### Set Up SSH Keys

```bash
# Generate SSH key
ssh-keygen -t ed25519 -C "your-email@example.com"

# Start SSH agent
eval "$(ssh-agent -s)"

# Add key to agent
ssh-add ~/.ssh/id_ed25519

# Copy public key
cat ~/.ssh/id_ed25519.pub
```

#### Customize Desktop

* **Wallpaper**: Right-click desktop → Configure Desktop
* **Theme**: System Settings → Appearance
* **Panel**: Right-click panel → Configure Panel
* **Shortcuts**: System Settings → Shortcuts

#### Optional: Enable Wayland

By default, RedCloud uses X11 for stability. To enable Wayland:

1. Logout
2. At SDDM login screen, click session type icon
3. Select "Plasma (Wayland)"
4. Login

***

### Virtual Machine Installation

#### VMware Workstation/Player

**Settings**:

* Guest OS: Debian 13.x 64-bit
* Memory: 4096MB minimum, 8192MB recommended
* Processors: 2+ cores
* Hard Disk: 20GB+ (50GB recommended)
* Network: NAT or Bridged

#### VirtualBox

**Settings**:

* Type: Linux
* Version: Debian (64-bit)
* Memory: 4096MB+
* Hard Disk: 20GB+ VDI (dynamically allocated)
* Enable EFI: System → Enable EFI
* Network: NAT or Bridged

**Post-Install**:

```bash
# Install VirtualBox Guest Additions
sudo apt install virtualbox-guest-utils virtualbox-guest-x11
```

#### KVM/QEMU

**Create VM**:

```bash
# Using virt-manager (GUI)
virt-manager

# Or virt-install (CLI)
virt-install \
  --name redcloud \
  --memory 4096 \
  --vcpus 2 \
  --disk size=20 \
  --cdrom /path/to/redcloud.iso \
  --os-variant debian11 \
  --network bridge=virbr0
```

**Post-Install**:

```bash
# Install QEMU guest agent
sudo apt install qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo systemctl start qemu-guest-agent
```

***

### Troubleshooting Installation

#### Calamares Won't Start

```bash
# Check system logs
journalctl -xe | grep calamares

# Try starting manually
sudo calamares -d  # Debug mode
```

#### Installer Crashes During Installation

* Check available disk space: `df -h`
* Verify ISO integrity (checksum)
* Try different partitioning scheme
* Check logs: `/var/log/Calamares.log`

#### Bootloader Installation Fails

* Ensure EFI partition is mounted at `/boot/efi`
* Check UEFI vs BIOS mode match
* Disable Secure Boot
* Try legacy BIOS mode if UEFI fails

#### System Won't Boot After Installation

**See**: Troubleshooting Guide

Common fixes:

* Boot from live USB
* Chroot into installed system
* Reinstall GRUB bootloader

#### Disk Encryption Issues

* Ensure passphrase is memorable
* Test passphrase during setup
* Write down passphrase securely
* No passphrase recovery possible if forgotten

***

### Next Steps

#### Essential Post-Install Tasks

* Update system: `sudo apt update && sudo apt upgrade`
* Configure cloud credentials (AWS, Azure, GCP)
* Set up SSH keys for GitHub/GitLab
* Configure firewall (if needed)
* Install additional software using APT

***

### Quick Reference

| Task                 | Command                               |
| -------------------- | ------------------------------------- |
| Launch installer     | `sudo calamares`                      |
| Update system        | `sudo apt update && sudo apt upgrade` |
| Install/update tools | `redcloud -u` or `redcloud --update`  |
| Check disk space     | `df -h`                               |
| View system logs     | `journalctl -xe`                      |

**Installation Complete!** Welcome to RedCloud OS.