Skip to content

Latest commit

 

History

History
687 lines (443 loc) · 25.3 KB

running-on-proxmox-debian.md

File metadata and controls

687 lines (443 loc) · 25.3 KB
Raw

Proxmox VE + PiBuilder + IOTstack

This tutorial walks you through the process of installing a Debian Bookworm guest system on a Proxmox VE instance, and then using PiBuilder to construct a platform for IOTstack.

contents

Assumptions

  1. Your hardware platform meets the Proxmox minimum system requirements.
  2. You have already downloaded and installed Proxmox VE on your platform.
  3. You are able to use a web browser to connect to the Proxmox VE GUI on port 8086.
  4. You are able to login to the Proxmox VE GUI as root.

Definitions

Wherever you see any «guillemot» delimited placeholders in these instructions, replace the entire placeholder (including the guillemots) with its actual value:

  • placeholder for your Proxmox VE instance:

    • «proxmox_root_password» = the password set for the root user during the installation of the instance.

  • placeholders for your guest system:

    • «guest_host» = the host name given to the guest system (eg prx-iot).
    • «guest_user» = the account name of the ordinary user set during the installation of the guest (eg alan).
    • «guest_user_password» = the password for «guest_user».

Phase 1 - get installation media

This phase walks you through the process of downloading the installation media for Debian. You only need to complete the steps in this phase once. You will be able to construct any number of Debian Guest systems from the same installation media.

  1. Use your web browser to open https://www.debian.org.

  2. Click "Download". Your browser should begin downloading the latest Debian installer onto your support host (Linux, macOS, Windows). The file will have a name like debian-12.1.0-amd64-netinst.iso. This is generally referred to as an .iso, indicating that the file is in ISO9660 (Optical Disc) format.

  3. Use your web browser to:

    • Connect to your Proxmox VE instance on port 8006
    • Login as root

    Then. by reference to the screen-shot below:

    ISO images list

    • Select the "Server View" 🄰
    • Select your server by name 🄱 (the server in this example is named "bauxite")
    • If the hierarchy is not expanded, expand it by clicking the ﹥ so it turns into ⋁
    • Select the "local" storage option 🄲
    • Select the "ISO Images" grouping 🄳
    • Click the "Upload" button 🄴

    In the file selection dialog that opens:

    ISO upload form

    • Click the "Select File" button 🄵

    • Use the file picker to select the .iso you downloaded from https://www.debian.org.

      Ignore the C:\fakepath in the dialog

    • Click the "Upload" button 🄶

    • The uploaded file will appear in the list 🄷.

Phase 2 - construct Debian guest

This phase walks you through the process of creating a Debian guest system. You can construct any number of Debian Guest systems from the installation media downloaded in the previous phase.

Create virtual machine

  1. Use your web browser to:

    • Connect to your Proxmox VE instance on port 8006
    • Login as root
    • Select the "Pool View" 🄹
    • Click "Create VM" 🄺

    Ignore reference points 🄻, 🄼 and 🄽; we will come to those later.

  2. In the "Create Virtual Machine" dialog, work through the tabs in order, clicking Continue at the end of each:

    • "General" tab:

      • "Name" field: enter a name for your guest (eg "prx-iot")

    • "OS" tab:

      • "ISO image" popup menu: select debian-12.1.0-amd64-netinst.iso

      This is the image you downloaded in the previous phase.

    • "System" tab:

      • "Qemu Agent" checkbox: enable.

    • "Disks" tab:

      • "Disk size (GiB)" field: the default is 32GB which is usually sufficient but you can adjust it as you see fit.
      • "Discard" checkbox: enable this if your underlying physical storage media is a Solid State Disk (SSD).

    • "CPU" tab:

      • "Cores" field: this defaults to a single core. At least two cores are recommended.

    • "Memory" tab:

      • "Memory (MiB)" field: this defaults to 2048MB. At least 4096MB is recommended.

    • "Network" tab:

      • accept all defaults

    • "Confirm" tab:

      • Click Finish

  3. Click the newly-created guest 🄻 to select it.

  4. Click the "Console" 🄼 to select the guest's console.

  5. Click the "Start Now" button 🄽.

  6. The guest will boot from the installation .iso:

    • Choose "Graphical install" and press return

    • Respond as appropriate to the screens:

      • "Select a language"

      • "Select your location"

      • "Configure the keyboard". Here's a tip from Andreas Spiess:

        Correct selection of your keyboard is essential. Otherwise, password entry might not work as you expect. For example, the German keyboard has Y and Z switched. You do not see your password as you type so you think it contains a Y but it's actually a Z.

    • "Configure the network":

      • At "Please enter the host name for this system", choose an appropriate name for this virtual «guest_host».

        Notes:

        1. Your DHCP server may suggest a host name but you will almost certainly want to change it.
        2. You can use letters (all lower case by convention), digits and dashes. For example "prx-iot".
        3. The name you choose here can be the same as the one you chose in the General tab of the Create Virtual Machine dialog, or it can be different.
        4. The name you choose here is the name by which your guest system will be known. For example, if you choose "prx-iot" then the $HOSTNAME variable of your guest will be prx-iot and the guest system will be reachable via the multicast DNS name of prx-iot.local.

      • At "Domain name", enter a domain name (if appropriate) or leave it blank.

        Your DHCP server may suggest a domain name.

    • "Set up users and passwords":

      • Leave both root password fields empty.

        Key points:

        1. If you accept this advice and do not assign a root password then the user you create in the next step will be given the ability to run sudo. This is similar to the privileges given to the default pi user on a Raspberry Pi. These instructions assume you accept this advice.
        2. If you ignore this advice and decide to assign a root password anyway then you should stop following these instructions.

      • At "Full name for the new user", enter the full (long) username for «guest_user» (eg "Alan Turing").

      • At "Username for your account", either accept the default or enter a (short) username for «guest_user» (eg "alan").

      • At "Choose a password for the new user", set and confirm a «guest_user_password».

    • "Configure the clock":

      • At "Select the state or province to set your timezone", make an appropriate choice.

    • "Partition Disks":

      • At "Partitioning method", choose "Guided - use entire disk".
      • At "Select disk to partition", accept the default.
      • At "Partitioning scheme", accept the recommendation of all files in one partition.
      • Leave "Finish partitioning and write changes to disk" selected.
      • At "Write the changes to disks?", select "yes".

  7. The installer will copy the base system from the .iso to the allocated (virtual) partition.

  8. At "Scan extra installation media?", leave the default at "No".

  9. "Configure the package manager":

    • "Debian archive mirror country", select a nearby mirror.
    • "Debian archive mirror", either accept the default or select an appropriate alternative.
    • If you need to set up a proxy, enter the details; otherwise leave the field blank.

  10. Respond to the "popularity contest" question as you think appropriate.

  11. In the "Software selection" panel:

    • "Debian desktop environment": You have two choices:

      1. You can leave this enabled and choose one or more of the windowing environments:

        • The installation takes longer and occupies more space on the virtual disk (~3GB);
        • The resulting guest boots into a windowing environment but you have the ability to instruct the system to boot to the console;
        • Network Manager is installed and configured; and
        • The Avahi daemon (multicast DNS) is installed and configured, or

      2. You can disable the desktop environment entirely:

        • The installation is significantly faster and uses less space;
        • The resulting guest boots to the console (there is no ability to switch to a Desktop environment)
        • Network Manager is not installed; and
        • The Avahi daemon (multicast DNS) is not installed.

      If your goal is to construct a server-class system for running IOTstack then I recommend disabling the desktop environment. However, if you need a user-class system which also happens to run IOTstack as a service then leaving the desktop environment enabled may be more appropriate. Your system, your rules!

    • enable "SSH server". This is important. Please do not skip this step.

  12. The installer will install your selected software.

  13. "Install the GRUB boot loader":

    • At "Install the GRUB boot loader to your primary drive?", accept "Yes" (the default).
    • At "Device for boot loader installation", select /dev/sda.

  14. At "Installation complete", ignore the reminder to remove the installation media. Proxmox VE handles this automatically.

  15. Your system will reboot. There is no need to respond to any of the boot-time prompts. Eventually, you will see a screen containing the full username you set earlier.

Phase 3 - guest configuration

guest pre-configuration

This pre-configuration step is only needed if you elected to run from the console. If you enabled one or more of the Desktop options, you can jump straight to guest user configuration.

A limitation of the Proxmox VE console window for a guest is that copy and paste doesn't work so you will need to enter commands by hand:

  1. In the Proxmox-VE GUI, select your guest 🄻 and click the console 🄼.

  2. Login using the console window 🄽. Remember to use the «guest_user» credentials you set earlier. There is no root account!

  3. Get a privileged shell:

    $ sudo -s

    You will be asked to re-enter your login password. The prompt will change to # to indicate that you are running as root.

  4. Run the following commands:

    # apt update
# apt install -y network-manager avahi-daemon
# systemctl restart sshd

    The avahi-daemon provides multicast Domain Name Services (mDNS). After this, the guest system will respond to the name «guest_host».local.

  5. Finish off by pressing control+d twice to exit the privileged shell and the console session.

guest user configuration

Although these commands could be executed from the guest console or a Terminal session opened in the Desktop windowing environment, you would need to type each command by hand. A limitation of the NoVNC interface prevents you from using clipboard services to paste commands into the guest. That's error-prone and, for that reason, the remainder of these instructions assume you will be working via SSH.

Open a Terminal window on your support host (eg your Mac/PC). From the Terminal window:

  1. Ensure your SSH "known hosts" file is in a predictable state:

    $ ssh-keygen -R «guest_host».local

    You may get an error from this command. That's OK. It's simply a protective measure.

  2. Login to the guest system:

    $ ssh «guest_user»@«guest_host».local

    You should expect to see the "trust on first use" (aka TOFU) challenge ("The authenticity of host … can't be established"). Respond with "yes" and press return.

    Supply the «guest_user_password» when prompted.

    Note:

    • You can't use SSH to login to the «guest_host» as root. You must connect using the «guest_user» username.

  3. Confirm that you can execute commands using sudo:

    $ sudo echo "hello"

    Supply the «guest_user_password» when prompted.

    Note:

    • If you are not able to execute commands using sudo, it probably means that you set a password for the root user, even though the instructions advised against doing that. Your best course of action is to destroy this guest system and start again.

  4. This step is only needed if you elected to run from the console. Skip to the next step if you enabled any of the Desktop options. Otherwise, run the following commands:

    $ ip link show
$ nmcli conn show

    The output from the first command will be something like this:

    1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: ens18: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether bc:24:11:c7:58:1e brd ff:ff:ff:ff:ff:ff
    altname enp0s18

    The output from the second command will be something like this:

    NAME  UUID                                  TYPE      DEVICE 
lo    1a328f3f-8f60-4249-9355-c9181202b97b  loopback  lo

    Taken together, the output from ip link shows that Proxmox-VE has defined a (virtual) PHY (OSI Layer 1 physical interface) named ens18, while the output from nmcli shows that Network Manager is not in control of that interface. It is better to let Network Manager control your interfaces so this problem should be fixed.

    Typically, a Proxmox-VE guest only has a single networking interface and ens18 appears to be the default name, so the command you are most likely to need to run is:

    $ sudo sed -i.bak -e '/ens18/ s/^/#/' /etc/network/interfaces

    However, if the output from ip link show identifies:

    • A different interface name then you should edit the command accordingly. For example, if the interface was named ens20 then the command would be:

       $ sudo sed -i.bak -e '/ens20/ s/^/#/' /etc/network/interfaces

    • multiple interfaces (other than lo) then you repeat the -e «script» syntax. For example, if two interfaces ens18 and ens19 were displayed, then the command would be:

       $ sudo sed -i.bak -e '/ens18/ s/^/#/' -e '/ens19/ s/^/#/' /etc/network/interfaces

    Once sed has edited /etc/network/interfaces, you need to make Network Manager aware of the change, like this:

    $ sudo systemctl restart NetworkManager.service

  5. This is an optional step. If the font size in the Proxmov-VE console is too small to read comfortably, you can exercise some control over that by running:

    $ sudo dpkg-reconfigure console-setup

    Good choices are UTF-8 (default), Latin 1 & 5 (default), TerminusBold, then whatever character size you like.

  6. Run the following commands, one at a time:

    $ echo "$USER  ALL=(ALL) NOPASSWD:ALL" | sudo tee "/etc/sudoers.d/$USER" >/dev/null
$ sudo usermod -G adm -a $USER
$ sudo reboot

    Explanation:

    1. The first line gives the current user the ability to execute sudo commands without needing a password.
    2. The second line adds the current user to the adm group (administration).
    3. The reboot is needed for some of the earlier commands to take effect.

    After the reboot, «guest_user» will have exactly the same privileges as the default pi user on a Raspberry Pi and, in particular, the ability to run sudo commands without a password prompt.

Phase 4 - clone PiBuilder

  1. Login to the guest system:

    $ ssh «guest_user»@«guest_host».local

    Supply the «guest_user_password» when prompted.

  2. Verify that the user has the ability to run sudo without a password:

    $ sudo echo "hello"

    If you are prompted for a password to run the sudo command, go back to the previous phase and check your work.

  3. Clone PiBuilder:

    $ sudo apt update ; sudo apt install -y git
$ git clone https://github.com/Paraphraser/PiBuilder.git ~/PiBuilder

    If you have customised a clone of PiBuilder which you want to use rather than the version on GitHub, adapt the URL appropriately.

  4. Logout (control+d).

Tip:

  • If you wish to use Proxmox's facilities to take a snapshot of your guest OS before you start running the PiBuilder scripts, this is the place to do it.

Phase 5 - run PiBuilder scripts

Script 01

  1. Login to the guest:

    $ ssh «guest_user»@«guest_host».local

  2. Run the first script:

    $ ./PiBuilder/boot/scripts/01_setup.sh

    There is no need to pass the «guest_host» argument to this script. You already entered the name for this host at "Please enter the host name for this system".

    Note:

    • If you elected to install the Debian desktop and one or more windowing environments then a side-effect of the 01 script is to boot the Proxmox-VE guest to the console. If you want to re-enable the Desktop login, run the following command:

       $ sudo systemctl set-default graphical.target

      If you subsequently decide to boot to the console, run:

       $ sudo systemctl set-default multi-user.target

      Both commands take effect on the next reboot.

Script 02

  1. Login to the guest:

    $ ssh -4 «guest_user»@«guest_host».local

  2. Run the second script:

    $ ./PiBuilder/boot/scripts/02_setup.sh

Script 03

  1. Login to the guest:

    $ ssh «guest_user»@«guest_host».local

    The previous 02 script disabled IPv6 so there is no further need to use the -4 option.

  2. Run the third script:

    $ ./PiBuilder/boot/scripts/03_setup.sh

Script 04

  1. Login to the guest:

    $ ssh «guest_user»@«guest_host».local

  2. Run the fourth script:

    $ ./PiBuilder/boot/scripts/04_setup.sh

Script 05

  1. Login to the guest:

    $ ssh «guest_user»@«guest_host».local

  2. Run the fifth script:

    $ ./PiBuilder/boot/scripts/05_setup.sh

Tip:

  • If you wish to use Proxmox's facilities to take a snapshot of your guest OS before you start doing anything with IOTstack, this is the place to do it.

Phase 6 - running IOTstack

At this point, you have two choices:

  • if you are just getting started with IOTstack, go to running the menu.
  • if you intend to migrate an existing IOTstack installation to your Debian guest, go to migrating IOTstack.

running the menu

  1. Login to the guest:

    $ ssh «guest_user»@«guest_host».local

  2. Change your working directory:

    $ cd ~/IOTstack

  3. Initialise your time-zone:

    $ echo "TZ=$(cat /etc/timezone)" >>.env

    This copies the timezone for your Debian guest into the file ~/IOTstack/.env, which makes it available to any containers which define their TZ variables like this:

    - TZ=${TZ:-Etc/UTC}

    That statement says "if TZ is defined in .env then use its value, otherwise default to Etc/UTC. It is an effective way of making sure all containers that support TZ run on the same timezone as your operating system and saves you the trouble of editing the same environment variable in each service definition.

  4. Run the menu and choose your containers:

    $ ./menu.sh

    The first time you run the menu, there will be a delay while the script constructs a virtual environment for Python.

  5. Bring up your stack:

    $ docker-compose up -d

migrating IOTstack

Have you been using IOTstackBackup to backup your existing IOTstack system?

using IOTstackBackup

In general, you will want to take a backup immediately before you do the migration process so:

  1. Login to your old IOTstack system:

    $ ssh «user»@«host».local

    where «host» is the name of your old IOTstack device, and «user» is the username on your old IOTstack device.

  2. Run a backup:

    $ iotstack_backup

  3. List your backups directory and use the timestamps embedded in the file names to identify the backup files that were just created. For example:

    2023-09-30_1138.iot-hub.backup-log.txt
2023-09-30_1138.iot-hub.general-backup.tar.gz
2023-09-30_1138.iot-hub.influx-backup.tar

    The «runtag» is the string comprising the date, time and hostname. In the above, the hostname is "iot-hub" so the «runtag» is:

    2023-09-30_1138.iot-hub

    Make a note of your «runtag» because you will need it later. Do not be concerned by the fact that the hostname portion is the name of your old system. It is exactly what you want!

  4. Logout from the old system by pressing control+d.

  5. Login to your newly-created guest system:

    $ ssh «guest_user»@«guest_host».local

  6. In order to function properly, IOTstackBackup needs the following files to be in place:

    • ~/.config/iotstack_backup/config.yml (required)
    • ~/.config/rclone/rclone.conf (optional)

    The rclone.conf is only needed if you have been using the RCLONE method (eg your backups are being sent to Dropbox).

    You can provide those files to PiBuilder so that they are installed automatically. If you have not done that, then you need to fix that problem now, like this:

    1. These steps are required:

      $ mkdir -p ~/.config/iotstack_backup
$ cd ~/.config/iotstack_backup
$ scp «user»@«host».local:.config/iotstack_backup/config.yml .

      where «host» is the name of your old IOTstack device, and «user» is the username on your old IOTstack device. You may be prompted to permit the connection, and for a login password.

    2. You only need to do these steps if you have been using the RCLONE method:

      $ mkdir -p ~/.config/rclone
$ cd ~/.config/rclone
$ scp «user»@«host».local:.config/rclone/rclone.conf .

  7. Now you can run the restore:

    $ cd
$ iotstack_restore «runtag»

    where «runtag» is the value you made a note of earlier. For example:

    $ iotstack_restore 2023-09-30_1138.iot-hub

    The iotstack_restore script will fetch the backup files using your chosen method (SCP, RSYNC or RCLONE) and then invoke subordinate scripts to restore your stack. Once again, do not be concerned by the fact that the hostname portion is the name of your old system. It is exactly what you want!

  8. Once the restore completes, you can bring up your stack:

    $ cd ~/IOTstack
$ docker-compose up -d

using migration assistant

Follow the instructions at IOTstackBackup migration assistant.

Note:

  • You can also use the migration assistant even if you have IOTstackBackup installed and configured on your old machine. Follow the link to the instructions above, then just skip step 2.

Home Assistant (Supervised)

If you wish to install Home Assistant on the same Proxmox VE instance, follow the instructions here.