Skip to content

Setting up the Website Server

This document explains how to set up or rebuild the website server that hosts install.whitebox.aero.

Prerequisites

  • An Ubuntu server (24.04 or later recommended)
  • SSH access with sudo privileges
  • Ansible installed on your local machine
  • Domain install.whitebox.aero pointing to your server's IP

Server Configuration

1. Add the server to Ansible inventory

Edit ansible/hosts.yml and add the website server:

website_server:
  hosts:
    website_01:
      ansible_host: YOUR_SERVER_IP
      ansible_user: root
      ansible_port: 22

2. Run the Ansible playbook

From the project root directory:

cd ansible
ansible-playbook setup_website.yml

This playbook will:

  • Update system packages and perform a full system upgrade (apt dist-upgrade)
  • Configure automated Ubuntu updates with automatic reboot at 03:00 when needed
  • Install and configure Nginx
  • Set up the redirect service for install.whitebox.aero
  • Install and configure SSL certificates via Let's Encrypt (certbot)
  • Configure automatic SSL certificate renewal

How It Works

The install.whitebox.aero service works as a smart proxy:

  1. When users access install.whitebox.aero, the nginx server proxies the bin/install.sh script from the GitLab repository
  2. By default, it serves the main branch
  3. Users can specify a different branch using the branch parameter: 
    # Fetch install script from a specific branch AND clone from that same branch
curl -fsSL https://install.whitebox.aero/?branch=feature/my-branch | bash

# Or just use main (default)
curl -fsSL https://install.whitebox.aero | bash
  4. nginx automatically injects the branch into the script using sub_filter, so users only need to specify it once in the URL
  5. Invalid branch names return a 400 error to prevent accidental installations

Rebuilding the Webserver

If you need to rebuild or update the webserver configuration:

1. Make changes to the Ansible playbook or templates

  • Main playbook: ansible/setup_website.yml
  • Nginx config template: ansible/templates/nginx/install-redirect.conf
  • Related tasks:
    • ansible/tasks/setup_nginx.yml
    • ansible/tasks/configure_install_redirect.yml
    • ansible/tasks/setup_ssl_certbot.yml

2. Run the playbook again

cd ansible
ansible-playbook setup_website.yml

The playbook is idempotent, so it's safe to run multiple times.

3. Verify the changes

Test the different scenarios:

# Test basic redirect
curl -I https://install.whitebox.aero

# Test branch parameter
curl -I "https://install.whitebox.aero/?branch=main"

# Test invalid branch (should return 400 error)
curl -I "https://install.whitebox.aero/?branch=invalid@branch"

# Test actual script download
curl -fsSL https://install.whitebox.aero | head -n 5

Automated Updates

The server is configured to automatically:

  • Update packages daily
  • Install security updates automatically
  • Reboot at 03:00 when kernel updates require it
  • Remove unused packages and dependencies

This configuration is managed by the unattended-upgrades package and can be customized in the Ansible playbook at ansible/setup_website.yml.