FullPageOS: a Raspberry Pi image that boots straight into one full screen webpage

The problem FullPageOS solves, and the hardware it expects

A Raspberry Pi with a screen attached usually boots into a desktop, waits for someone to log in, and then needs a browser opened by hand. FullPageOS removes those steps. The README describes it as "a Raspberry Pi distribution to display one webpage in full screen" and states that it includes Chromium out of the box plus the scripts needed to load it at boot. That is the entire product: a prebuilt Raspbian image with the kiosk behaviour already wired in.

The audience is narrow and specific. Digital signage, a wall mounted dashboard, a status board, a shop window display, or any panel that should show one page and nothing else. The requirements section sets the floor: Raspberry Pi 2 and newer, or a device running Armbian. Older Raspberry Pis are not supported, and the README points at two issues for that limitation rather than explaining it. You also need an SD card of 4GB or larger, Class 10, and a 2A power supply. The README notes that in early June 2020 the image size was 3GB, which is why the card floor is where it is.

The project began as a fork of OctoPi and later moved to the CustomPiOS build system, which is the same tooling behind several other Raspberry Pi distributions. That lineage is visible in the repository: src/ holds the build scripts, media/ holds artwork, and testing/ holds test material. There is no application server and no daemon to operate. The deliverable is an SD card image.

How the boot-to-URL mechanism actually works

The configuration surface is a single file on the boot partition: /boot/firmware/fullpageos.txt. You write the URL you want into that file, and the boot scripts read it and hand the address to Chromium, which starts full screen. Because the file sits on the first partition, you can edit it while the card is still in a card reader, before the Pi ever boots. That is the design decision that matters most here: the target URL is data on a FAT partition, not a setting buried in a user profile.

The README also documents one substitution. The URL may contain the variable {serial}, which is replaced with the device's serial number. That turns one image into many uniquely identified displays. If you flash ten cards from the same image and each URL contains {serial}, each panel can report which unit it is without per-device editing.

The default page is FullPageDashboard, a separate project by another author. The README describes it as letting you "add multiple tabs changes that switch automatically", which is how the project covers multi-page signage without adding its own rotation logic. If you want several pages cycling, that behaviour comes from the page you point FullPageOS at, not from the image. Remote access is handled by a preconfigured X11VNC server, and the README gives its password as 'raspberry', independent of the user account password. A custom splash screen can replace the kernel messages shown during boot.

FullPageOS setup: flash, configure WiFi, first boot

The README's usage steps are short. Unzip the image and write it to an SD card the same way as any other Raspberry Pi image. Then, while the card is still mounted as a flash drive, edit wifi.nmconnection on the first partition to set your network credentials. Boot the Pi. It comes up on the network as fullpageos.local if your machine supports Bonjour, otherwise use the address your router assigned.

The default credentials are stated plainly in the README: username "pi", password "raspberry". Change the account password with passwd, and consider changing the VNC password separately with x11vnc -storepasswd, because the two are not linked.

ssh [email protected]
passwd
x11vnc -storepasswd

To point the display at your own page, edit the URL file on the boot partition. The README does not print a sample line for fullpageos.txt, so the safest first move is to read the file that shipped with your build and replace the URL it contains, keeping the same format.

The README gives one worked example of moving files onto the device, using rsync to copy a Chrome extension build folder into the user's home directory:

rsync -av <extension-build-folder>/ [email protected]:extensions/<extension-name>/

Extensions themselves are installed from the Chrome Web Store, or loaded from your own build, after opening a new tab with ctrl + t. Note that this assumes the Chromium instance is reachable with a keyboard, which is a kiosk-mode assumption worth checking before you rely on it.

Where FullPageOS is the wrong choice

The image does one thing, and the README does not claim otherwise. If you need a general purpose Raspberry Pi desktop, a media centre, or a machine that runs local applications alongside a browser, this is the wrong starting point. You would be stripping out the kiosk behaviour rather than adding to it.

The configuration file is also a single point of failure with no documented fallback. The README describes reading the URL from /boot/firmware/fullpageos.txt and the {serial} substitution, and it stops there. It does not document what happens if the file is missing, empty, or contains a URL that fails to resolve, and it does not document a retry or a recovery page. If your signage depends on a remote page, a network outage at boot is an unhandled case as far as the documentation goes.

Hardware support is another boundary. Raspberry Pi 2 and newer, or Armbian on another device. Anything older is explicitly out of scope, and the README links to two issues instead of a workaround. The power and card requirements (2A supply, Class 10 card, 4GB or more) are the kind of constraint that shows up as instability rather than as a clean error message when you ignore it.

Finally, the project is a build system as much as a product. If you only want to flash a card, you never touch src/. If you want to change what is inside the image, you are now maintaining a CustomPiOS build, with the disk space and privilege requirements that implies.

Building your own image, and how it differs from flashing one

The README separates consuming FullPageOS from producing it. Building requires qemu-arm-static, CustomPiOS, a downloaded Raspbian image, root privileges for chroot, Bash, realpath, sudo and jq. The script calls sudo itself, so running it as root without sudo will not work. About 2.5GB of free space is needed.

The documented build sequence clones both repositories, fetches the Raspbian Lite image, updates the CustomPiOS paths, loads the loop module, and runs the build script:

sudo apt install coreutils p7zip-full qemu-user-static
git clone https://github.com/guysoft/CustomPiOS.git
git clone https://github.com/guysoft/FullPageOS.git
cd FullPageOS/src/image
wget -c --trust-server-names 'https://downloads.raspberrypi.org/raspios_lite_armhf_latest'
cd ..
../../CustomPiOS/src/update-custompios-paths
sudo modprobe loop
sudo bash -x ./build_dist

The output image lands in src/workspace. Variants are supported, with an example in src/variants/example, and are built by passing the variant name to the same script:

sudo bash -x ./build_dist [Variant]

Settings can be overridden by creating src/config.local, which takes precedence over src/config. The README specifically mentions ZIP_IMG for pointing the build at a different Raspbian image; by default the newest file matching *-raspbian.zip in src/image is used. Docker and Vagrant paths are documented elsewhere, in the CustomPiOS wiki and in src/vagrant respectively. The Vagrant route needs vagrant later than 1.9 and, unless you configure otherwise, must run as root for NFS folder sync to work.

Alternatives: a plain Raspberry Pi OS image versus a purpose-built kiosk distro

The obvious alternative is Raspberry Pi OS itself, with a browser installed and an autostart entry that launches it in kiosk mode. The difference is where the configuration lives and who maintains it. With Raspberry Pi OS you own the autostart file, the browser flags, the display settings and the upgrade path, and you get a full desktop you can fall back to when something breaks. With FullPageOS the boot-to-URL behaviour is already integrated and the URL is a text file on the boot partition, but you inherit the project's build system when you want to change anything below that level.

A second alternative is a browser-only kiosk appliance built on a minimal base, where the display server does nothing except run the browser. That is closer to what FullPageOS produces, but you assemble it yourself. The trade is control against the effort of getting boot-to-full-screen right on the first try, including the details FullPageOS has already settled: VNC access, a splash screen, and the {serial} substitution.

There is also a class of signage products that manage content centrally, pushing playlists to each device. FullPageOS has no such control plane. The README's answer to multiple pages is the default FullPageDashboard page, which rotates tabs inside the browser. If you need scheduling, remote content updates, or fleet reporting, you are looking at a different category of tool, and the URL file is not a substitute for it.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-07-13. The most recent release listed is 1.0.0-rc1 from 2026-06-04, a release candidate rather than a final 1.0.0. Before that, 0.14.0 came out on 2025-07-14 and 0.13.0 on 2023-10-22. The gap between 0.13.0 and 0.14.0 is roughly twenty months, and the gap before it is longer still. That cadence is worth knowing if you plan to track upstream: releases are infrequent, and the current line is still at a release candidate.

Upgrading is not an in-place operation in the usual sense. The README's usage model is flash an image, edit the WiFi connection file and the URL file, boot. Moving to a newer build means reflashing and reapplying those edits unless you have kept them somewhere else. Any extensions you installed live on the device, not in the image, so they have to be reinstalled or restored with something like the rsync example the README gives. Budget for that whenever you move a fleet to a new build.

Licensing is GPL-3.0. The README states that FullPageOS is "100% free and open source and maintained by Guy Sheffer" and asks for donations. The practical implication of GPL-3.0 for a signage deployment is that if you redistribute a modified image, the licence terms attach to that distribution. What that means for your specific product is a question for a lawyer, not for this article. Note also that the image bundles Chromium, X11VNC and other components with their own licences, and the README does not enumerate them.

Editorial conclusion

Adopt FullPageOS when a Raspberry Pi 2 or newer has to show one URL unattended and you want the configuration to live in a text file on the SD card rather than in a desktop session. Do not adopt it if you need a normal desktop, a browser that survives a page crash without intervention, or hardware older than a Pi 2. Before flashing, verify the image at the official mirror, confirm your card is 4GB or larger and Class 10, and read the current fullpageos.txt on the boot partition so you know which URL the build will load.

Frequently asked questions

Official sources

1. guysoft/FullPageOS on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases