• Step 0 – Pi Preparation
  • Create an SD Card (using a “lite” image)
  • Enable Wifi & SSH for headless access
  • Change Pi passwd
• Step 1 – Configure Pi
  • Disable Auto-Login
  • Set Pi Hostname
  • Reboot
• Step 2 – Change Pi Username (optional)
  • Change Pi username
  • Login with new User
• Step 3 – Install OctoPrint

Step 0 – Pi Preparation

For this, you will need (obviously)

• Raspberry Pi
• SD Card
• SD Card Reader
• PC to format images
• Familiarity with Linux command line!

For my own setup, I have a Windows PC for day-to-day operation, and a Linux VM that I run when I need access to a Linux environment. By preference, I use Debian, which also forms the basis of the Raspberry Pi OS (Raspbian).

Create SD Card

Follow the instructions at https://www.raspberrypi.org/software/ to download the Raspberry Pi Imager and install one of the standard images. Personally, for a headless configuration, I will always pick the “lite” image.

For those feeling a little more adventurous, you can download the 64bit Pi OS Lite image here: https://downloads.raspberrypi.org/raspios_lite_arm64/images/

You should read the release notes for this (Forum page: https://www.raspberrypi.org/forums/viewtopic.php?t=275370) – it is in beta (at the time of writing) but should be stable enough for running octoprint and some basic services

Headless WiFI Access

Following the creation of your SD card, you should be able to plug it in and (in a windows system) be presented with the “boot” partition that is required to initialise the Raspberry Pi.

In the boot partition, create file wpa_supplicant.conf and fill in contents – Country code should be from ISO-3166 Country code list (List_of_ISO_3166_country_codes):

country=GB
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="NETWORK-NAME"
    psk="NETWORK-PASSWORD"
}

Create file ssh with no contents (the presence of this file is enough to enable SSH server)

Insert SD card into a suitable Pi and wait for it to boot.

Login to the newly configured server:

ssh pi@raspberrypi

Change Pi password

Best practice is to change the password from the well-known default, to something only you will know.

passwd

And follow the instructions to change the default password.

Step 1 – Configure Pi

Elevate to Super-user

sudo su -

Or run the following commands with sudo prefix

Disable Autologins

rm /etc/systemd/system/autologin@.service
rm /etc/systemd/system/getty@tty1.service.d/autologin.conf

Set Pi Hostname

Pick a hostname for the Raspberry Pi – here we will use “octopi” as the example, you should replace this with your specific name.

Change the hostname of the Pi:

vi /etc/hostname

change the entry “raspberrypi” to “octopi”

vi /etc/hosts

change the entry for 127.0.1.1 raspberrypi and replace the “raspberrypi” component with “octopi”, the line then reads 127.0.1.1 octopi

Reboot Pi

Finally, reboot the pi

reboot

Step 2 – Change Pi Username

As the username “pi” is well known, it is a good idea to change this. You will only be able to do this if there are no active sessions, so disabling auto-login (above) is a good idea. You can choose to forego that step and this, if you continue with the Pi username.

In tightly controlled lab environments, you might decide to use the root account, being mindful to disable SSH access and clear the password after you are done.

You could also do this using the OctoPrint account we will create later – you will either have to add that account to Sudoers, or set a password on root first, clearing it later.

Start by ssh’ing across to the pi:

ssh pi@octopi

Set Root Password

Elevate to root, then set the password for root

sudo su -
passwd

Set the password for root

Enable root SSH login

Edit the sshd config file:

sudo vi /etc/ssh/sshd_config

Locate the line

#PermitRootLogin prohibit-password

and add the entry beneath that:

PermitRootLogin yes

Restart sshd and exit the SSH session

sudo service sshd restart
exit

Reconnect with Root

Connect with root over ssh to ensure you have access:

ssh root@octopi

Enter the newly set root password when prompted.

Update Pi account

Rename user account, change default home directory and group:

usermod -l octo pi
usermod -d /home/octo -m octo
groupmod -n octo pi
exit

Logout out and test access

ssh octo@octopi

Use the password that you set for “pi” at the very first login.

Lock down root account

Reverse the changes to root, to re-secure the system

Lock the root password:

sudo passwd -l root

sudo vi /etc/ssh/sshd_config

Remove the line

PermitRootLogin yes

Restart ssh with sudo service sshd restart

Install SSH Key

Typically, SSH access is secured with a key. Install your key on the Pi for easy remote access:

ssh-copy-id octo@octopi

Step 3 – Setup OctoPrint

To setup OctoPrint, we need to setup the virtual environment that it will run in (this environment is a level of isolation that seperates OctoPrint from the rest of the system, and helps to prevent unauthorised access) and the user account to limit the access.

To help with the isolation, we can also install OctoPrint into the /opt folder which is where server specific applications are installed.

Start by logging in to your prepared Pi

ssh octo@octopi

Instruction here are based on the ocotprinty community post: https://community.octoprint.org/t/setting-up-octoprint-on-a-raspberry-pi-running-raspbian-or-raspberry-pi-os/2337

Install Prerequisites

sudo apt-get install python3-pip python3-dev python3-setuptools python3-venv git libyaml-dev build-essential

Setup User Account

Create an OctoPrint user account, with home directory /opt/octoprint, and add the user to the tty and dialout groups (necessary to access serial ports for 3D printers):

sudo useradd -G tty,dialout -m -d /opt/octoprint octoprint
sudo su octoprint
cd ~

Install OctoPrint

From the OctoPrint users home directory (/opt/octoprint) you should first create the virtual environment before you activate it.

python3 -m venv venv
source venv/bin/activate

This should put you in a Python virtual environment

Start by installing pip, then octoprint.

pip install pip --upgrade
pip install octoprint

finally, exit the virtual environment with

deactivate

Setup Octoprint Service

Download the OctoPrint service script:

wget https://github.com/OctoPrint/OctoPrint/raw/master/scripts/octoprint.service
sudo ln -s /opt/octoprint/octoprint.service /etc/systemd/system/octoprint.service

Edit the octoprint.service file and ensure the User and ExecStart lines looks like this:

User=octoprint
ExecStart=/opt/octoprint/venv/bin/octoprint

And enable the service:

sudo systemctl enable octoprint.service

Start Octoprint

At this point, you should be able to start OctoPrint

sudo service octoprint start

And plumb in the address of the Pi into a web browser to see the interface: http://octopi:5000/

If all has gone well, you should be presented with the OctoPrint web interface