pivilion/README.md

Manual

Pivilion is a decentralizing open source darknet web server project and gallery management software for the creation of autonomous & uncensored digital media art online galleries. It runs on low cost Raspberry Pi hardware and is built on top of Raspbian GNU/Linux with a server and Tor networking built in, utilizing the Tor network to host exhibitions out of the box.

Each Pivilion device receives a Tor onion domain automatically the first time it’s activated. The system provides the user with a CMS for publishing multimedia or websites within a gallery. It’s designed so that the author-curator can use any network (even public networks behind firewalls) to host an online exhibition.

Pivilion is primarily a long-term, open-ended new media art project propagating autonomous modes of art in the darknet, and is continuously including a large number of artists and cultural workers in its creation.

The documentation and the announcement of global #pivilion_dot events are available via the central website, hosted both on clearnet and as a hidden service on the Tor network, while the entire open source system is available via git.

Project website: pivilion.net

Required hardware:

- Raspberry Pi with WiFi
- min 8 GB SD card
- battery or power adapter

Installation on current Raspberry Pi OS

Pivilion supports Raspberry Pi OS Bullseye, Bookworm, and Trixie. Bookworm and newer systems use NetworkManager automatically; Bullseye installations using dhcpcd use the legacy hostapd backend. The repository layout and the original commands are preserved on both backends.

On a fresh Raspberry Pi OS Lite installation:

git clone https://gitlab.com/hacklab01/pivilion.git
cd pivilion
sudo ./install.sh
sudo reboot

The installer performs preflight checks, backs up managed configuration under /var/backups/pivilion, validates the deployed services, and restores the previous configuration if deployment fails. Additional maintenance modes are:

./install.sh --dry-run       # read-only preflight and proposed actions
sudo ./install.sh --check    # validate an existing installation
sudo ./install.sh --repair  # repeat deployment without replacing gallery content

The installer defaults to the user that invoked sudo, not to a hard-coded pi account. The installer automatically creates pivilion.conf at the externally visible root of the FAT boot partition, using the current system and saved Wi-Fi settings. Linux may mount that same root as /boot or /boot/firmware; users never need to expose that distinction. The hotspot is intentionally open and passwordless.

The boot file controls startup mode, upstream Wi-Fi SSID and PSK, Wi-Fi country and interface, hotspot name and channel, hostname, Pivilion user and paths, generator state, and PHP upload limit. Pivilion commands keep it synchronized. An 8–63-character Wi-Fi password entered there is replaced at boot with its derived 64-character WPA PSK. The PSK does not reveal the original text, but it still grants network access and must be treated as a secret. Invalid offline edits retain the root-protected last-known-good settings and create pivilion-error.txt beside the boot configuration.

Use pikey to save upstream Wi-Fi credentials, then onion and reboot to host through Tor. Use hotspot and reboot to run the local captive gallery at http://10.1.1.1/. HTTPS interception is intentionally not attempted because a local captive portal cannot present valid certificates for arbitrary sites. Changing PIVILION_MODE in the boot-partition configuration activates either mode during the immediately following boot; no second reboot is required.

If a phone joins but does not open its captive-login window, run pivilion diagnose on the Pi to verify DHCP/DNS, Apache rewrite handling, nftables, and the common Android, Apple, and Microsoft HTTP probes.

pivilion status distinguishes the requested next-boot mode from the last verified active mode and reports degraded activation. pivilion diagnose --json provides the same health checks for monitoring. The legacy pivilion-diagnose command remains an alias.

On the physical TTY, Pivilion appends its current IP, ASCII logo, and system status through /etc/issue.d/90-pivilion.issue; Raspberry Pi OS retains its normal Debian/hostname/TTY heading. The banner appears before login: rather than among systemd boot messages. SSH sessions receive the same status once after authentication.

Diagnostic exit codes are stable: 10 invalid configuration, 11 missing or unsupported hardware, 12 service/port conflict, 13 core service failure, 14 captive portal failure, 15 Tor/onion failure, and 20 installer failure.