Install Terminus on Windows

This guide covers the detailed steps of installing Terminus on your Windows system. This method leverages the Windows Subsystem for Linux (WSL) to create a Linux environment within Windows, where Terminus OS is then installed.

NOTE

Currently, Terminus on Windows has certain limitations including:

• Lack of distributed storage support
• Inability to add local nodes

We recommend using it only for development or testing purposes.

Prerequisites

Before you begin, ensure your system meets these requirements:

• A Windows machine meeting the following requirements:
  • CPU: 4 cores or above
  • RAM: 16 or above (available memory)
  • Storage: 64GB or above (available disk space)
  • Supported Systems:
    • Windows 10 or 11
    • Linux (on WSL2): Ubuntu 20.04 LTS or later; Debian 11 or later
• TermiPass mobile app installed on your smartphone
• Terminus Name created

INFO

Learn why you need a Terminus Name here.

Step 1: Install Terminus

1. Create a .wslconfig file in your Windows user directory (typically C:\Users\YourUsername\) with the following content:

   [wsl2]
   memory=16GB 
   swap=0GB

2. Open PowerShell as Administrator and run the following commands to install Ubuntu in your WSL environment:

   wsl --install -d Ubuntu-22.04
   wsl --update

   INFO

   You may need to restart your system after Ubuntu is installed if it's the first time installing WSL.

3. In PowerShell, run the following command to obtain Windows host IP:

   netsh interface ipv4 show addresses

   Note the IP Address of your WLAN or Ethernet interface. It should start with 192.xxx. You will need it when installing Terminus.

4. Set up port forwarding for your WSL server.

   a. Get the IP address of the WSL server.

   wsl ip address show eth0 `| grep inet `| grep -v inet6 `| cut -d ' ' -f 6 `| cut -d '/' -f 1
   # This typically returns an IP address in format of "172.xx.xx.xx"

   b. Set up port forwarding rules:

   netsh interface portproxy add v4tov4 listenport=80 listenaddress=0.0.0.0 connectport=80 connectaddress=<addr for hostname>
   netsh interface portproxy add v4tov4 listenport=443 listenaddress=0.0.0.0 connectport=443 connectaddress=<addr for hostname>
   netsh interface portproxy add v4tov4 listenport=30180 listenaddress=0.0.0.0 connectport=30180 connectaddress=<addr for hostname>
   
   # Replace <addr for hostname> with the IP address you get from step a.

5. Configure the Ubuntu environment.

   a. Open the Start menu and search for Ubuntu-22.04, and click on the Ubuntu icon to launch your Linux environment.

   wsl -d Ubuntu-22.04

   b. In Ubuntu, modify the /etc/wsl.conf file as specified below.

   NOTE

   Make sure you open the file with sudo privileges.

   [boot] 
   systemd=true  
   command="mount --make-rshared /"   # Add this line
   [network]
   generateHosts = false
   generateResolvConf = false # Allow manually managing hosts file and DNS settings
   hostname=terminus # Set the hostname for the WSL instance

   c. Shut down Ubuntu in PowerShell and restart it.

   wsl --shutdown Ubuntu-22.04

   d. In Ubuntu, modify the hosts file and the resolv.conf file:

   sudo sh -c "echo \"127.0.0.1 localhost\n \
   $(ip -4 addr show eth0 | grep -oP '(?<=inet\s)\d+(\.\d+){3}') $(hostname)\" > /etc/hosts && \
   echo \"nameserver 1.1.1.1\nnameserver 1.0.0.1\" > /etc/resolv.conf"

   This command binds Ubuntu's local IP with the host name, and configures DNS resolution to use Cloudflare's public DNS servers.

6. Install Terminus.

   a. In Ubuntu, run the following command to install the latest build of Terminus:

   curl -fsSL https://terminus.sh |  bash -

   b. During installation, enter the Windows host IP (192.168.xxx.xxx) you obtained earlier in step 3 when prompted. Then, press Enter to proceed.

   

   INFO

   If an error occurs during installation, use the following command to uninstall first:

   bash uninstall_cmd.sh

   After uninstalling, retry the installation by running the original installation command.

Step 2: Enter Terminus Name

At the end of the installation process, enter your domain name and Terminus Name as prompted by the system:

• If your Terminus Name is "alice@myterminus.com", press Enter or type myterminus.com for the domain name, then type alice for the terminus name.

• If your Terminus Name is "alice@helloworld.com", type helloworld.com for the domain name, then type alice for the terminus name.

INFO

To use a custom domain name, make sure the domain configuration has been completed as described in Create Domain.

Step 3: Get Initial System Info

Upon completion of the installation, the initial system information, including the Wizard URL and the initial login password, will appear on the screen. You will need them later in the activation stage.

Wizard URL

There are two Wizard URLs as shown the screenshot:

• The upper one is for internal network access.
• The lower one is for public network access.

Generally speaking, if your computer and Terminus are on the same network, use the internal network URL. If not, use the public network URL.

TIP

When using the internal network URL, please note:

• You might need to set up a reverse proxy during activation.
• If you're activating TermiPass by QR scanning, ensure your phone and Terminus are on the same network.

Initial Login Password

Please take note of the initial one-time password in the lower red square. You will need it in the Wizard page.

Next Steps

• Activate Terminus
• Log In to Terminus
• Manage Accounts with TermiPass